hardis:org:diagnose:what-will-break
Description
Command Behavior
Tells what will break in an org because of a dated Salesforce change, when, and what to do before it breaks.
The command starts with a list of every check, all selected: keep the ones to run. It then writes a main report with one row per thing that will break (an integration and its user, a Connected App, a data source, a range of API versions, a release update), and one row per check that found nothing, so a clean org gets a report that says so. A check with more than 20 findings lists the first 20, and a last row points to its detail report.
| Main report column | Content |
|---|---|
| Status | Error (the date has passed or is less than 60 days away), Warning, Info, Not checked (with the reason) or OK |
| What will break | What fails, for which app, user or data source, and when. On an OK row, what was checked. |
| Date | When it breaks: a day, "Enforced since", or a Salesforce release such as "Summer '28 (2028-06)" |
| What to do | The steps that fix this item and keep it from breaking again, or the report file that lists them |
| Salesforce announcement | The official Salesforce page of the change |
| How to fix | The How to fix section of the check, with the steps |
| Detail report | The report of the check, with every item it found |
| Check | Salesforce change | Production date | Salesforce announcement |
|---|---|---|---|
| Refresh tokens idle for 30 days | Refresh tokens unused for 30 days expire (invalid_grant) |
Since November 4, 2026 (sandboxes: October 21, 2026) | Article 005461275 |
| Integrations using their refresh token less than every 30 days | A monthly or quarterly sync loses its token between two runs | Since November 4, 2026 (sandboxes: October 21, 2026) | Article 005461275 |
| OAuth device flow | Only allowed on local External Client Apps with a localhost callback | November 30, 2026 | Article 005461280 |
| Use Any API Auth permission for SOAP login() | Every SOAP login() caller needs the permission (INSUFFICIENT_ACCESS otherwise) |
December 1, 2026 | Article 005132110 |
| Security token for SOAP login() from wide IP ranges | A trusted IP range wider than /8 (IPv4) or /29 (IPv6) no longer spares the security token | January 31, 2027 (sandboxes: December 15, 2026) | Article 005132110 |
| SOAP login() turned off after 6 months without use | Salesforce turns login() off in orgs where nobody called it in 6 months |
January 31, 2027 (sandboxes: December 15, 2026) | Article 005132110 |
| OAuth username-password and user-agent flows | Both flows are retired | February 20, 2027 | Release update |
| Salesforce Connect cross-org legacy authentication | Cross-org data sources must use a Named Credential | Spring '27 | Release update |
| SOAP login() retirement | SOAP login() is retired in API versions 31.0 to 64.0 |
Summer '27 | Article 005132110 |
| Connected Apps to move to External Client Apps | Connected Apps keep working, but Salesforce no longer fixes or supports them | Summer '27 | Release note |
| Calls to retired API versions | API versions 30.0 and older are retired, 31.0 to 40.0 are retired in Summer '28 | Summer '25 and Summer '28 | API 21.0 to 30.0, API 31.0 to 40.0 |
| Release updates due | Each release update is enforced on its due date | The due date of each release update | Release Updates (each release update links to its own article in Setup) |
Each check that found something also writes its own report. The legacy API check keeps the files of hardis:org:diagnose:legacyapi, including one file of API clients (IP addresses) per range of API versions.
The refresh token checks look at integrations only: idle tokens of API only users, and the refresh token use of an app run by an API only user or by one user only. A person whose token expires is asked to log in again: nothing breaks. Salesforce's own apps (mobile, Outlook, Salesforce CLI, Code Builder...) and the users Salesforce runs itself are left out.
Users listed in the project config key monitoringWhatWillBreakIgnoreUsers or the env var MONITORING_WHAT_WILL_BREAK_IGNORE_USERS (comma-separated) are skipped, for example an integration already being fixed.
This command replaces hardis:org:diagnose:legacyapi and hardis:org:diagnose:releaseupdates, which are deprecated. It is part of sfdx-hardis Monitoring and can output Grafana, Slack and MsTeams Notifications. When LEGACY_API or RELEASE_UPDATES is turned off in the monitoring config (monitoringDisable, or frequency off), the matching check is not run by default.
Agent Mode
Supports non-interactive execution with --agent:
sf hardis:org:diagnose:what-will-break --agent --target-org myorg@example.com
sf hardis:org:diagnose:what-will-break --agent --checks idleRefreshTokens,refreshTokenCadence,legacyApiVersions
In agent mode, and in CI, the list of checks is not shown: --checks picks them (comma-separated keys: idleRefreshTokens, refreshTokenCadence, deviceFlow, soapLoginPermission, soapLoginIpRange, soapLoginInactivity, usernamePasswordFlow, sfConnectLegacyAuth, soapLoginRetirement, connectedAppsToEca, legacyApiVersions, releaseUpdates), and all of them run when it is not given.
Technical explanations
The command's implementation:
- LoginHistory: a single aggregate SOQL query (grouped by user, login type, app, API version, IP address and status) reads the logins of the last
--lookback-daysdays (default and maximum 180, the LoginHistory retention) whoseLoginSubTypeis a SOAP API login,OAuth Device,OAuth Username-Passwordor anOAuth User-Agentflow.Application,ApiVersionandStatuscannot be filtered in SOQL but can be grouped. The Bulk API does not supportLoginHistory. When the aggregate query fails or returns 2000 groups, the raw logins are read instead. - Refresh token use: the
OAuth Refresh Tokenlogins are grouped by user, app, status and day (DAY_ONLY(LoginTime)), 20 users per query, a chunk being split in two when it reaches the 2000 groups limit. A user and app whose longest gap between two days of use is 30 days or more is reported, and so is one used on a single day (as information while that day is less than 30 days ago). Past 2000 user and app pairs, the users are grouped alone, then every active user is read. - Use Any API Auth: a describe confirms
PermissionSet.PermissionsUseAnyApiAuthexists, thenPermissionSetAssignmentis queried in chunks of 200 users, which covers profiles, permission sets and permission set groups. - OAuthToken: every token is read (Bulk, page by page past the 2500 tokens limit). The idle time is the time since
LastUsedDate(CreatedDatewhen never used). API only users come fromPermissionSetAssignmentonPermissionsApiUserOnly. - Trusted IP ranges:
SecuritySettings.Metadata.networkAccess.ipRanges(Tooling API). Profile login IP ranges cannot be read with SOQL and are not taken into account. - Username-password and user-agent flows:
OauthOidcSettings.Metadata(Tooling API) tells if both flows are already blocked in the org. - Salesforce Connect:
ExternalDataSourcerecords of typeSfdcOrgwithoutNamedCredentialId. - Connected Apps: the same usage list as hardis:org:diagnose:unsecure-connected-apps. A Connected App the org owns (its
ConnectedAppmetadata), used in the last 90 days, must be moved. - API versions: the
ApiTotalUsageevent log files, analyzed like hardis:org:diagnose:legacyapi. SOAPlogin()calls stay in its detail report: the SOAP login() retirement check covers them. - Release updates: Tooling API
ReleaseUpdaterecords in stageUpcomingorOverDue. Each one links to the Release Updates Setup page of the org, where its Salesforce article opens. A release update that enforces the change another check looks at (matched on itsDeveloperName) is merged into the rows of that check, unless that check did not run: the rows take its due date when it comes first, and the step to enable it. - Dates: all the Salesforce dates are in one table of
whatWillBreakDeadlines.ts.Organization.IsSandboxpicks the sandbox date when Salesforce gives one. When the org cannot be reached, the command fails instead of reporting the checks as not run. - Reports: the main CSV / XLSX (
what-will-break-<date>), then one report per check that found something (what-will-break-<check>-<date>). Usernames and IP addresses follow the anonymization settings. - Metrics:
IdleRefreshTokensExpiringSoon,IntegrationsRefreshingTooRarely,DeviceFlowUsers,SoapLoginUsersMissingPermission,SoapLoginUsersNeedingToken,UsernamePasswordFlowUsers,SfConnectLegacyDataSources,SoapLoginUsers,ConnectedAppsToMigrate,LegacyApiCalls,ReleaseUpdates. A check that is not selected, or cannot run on the org, sends no metric.
Parameters
| Name | Type | Description | Default | Required | Options |
|---|---|---|---|---|---|
| agent | boolean | Run in non-interactive mode for agents and automation | |||
| checks | option | Comma-separated keys of the checks to run, without the list of checks being shown. Available: idleRefreshTokens, refreshTokenCadence, deviceFlow, soapLoginPermission, soapLoginIpRange, soapLoginInactivity, usernamePasswordFlow, sfConnectLegacyAuth, soapLoginRetirement, connectedAppsToEca, legacyApiVersions, releaseUpdates. | |||
| debug -d |
boolean | Activate debug mode (more logs) | |||
| flags-dir | option | Import flag values from a directory. | |||
| idle-warning-days | option | Number of idle days from which the refresh token of an API only user is reported as about to expire (they expire after 30 days). | 20 | ||
| ignore-users | option | Comma-separated list of usernames to skip (merged with monitoringWhatWillBreakIgnoreUsers config and MONITORING_WHAT_WILL_BREAK_IGNORE_USERS env var). | |||
| json | boolean | Format output as json. | |||
| lookback-days | option | Number of days of LoginHistory to scan for SOAP login() and OAuth logins (maximum 180, the LoginHistory retention). | 180 | ||
| outputfile -f |
option | Force the path and name of the main report file. Must end with .csv | |||
| skipauth | boolean | Skip authentication check when a default username is required | |||
| target-org -o |
option | Username or alias of the target org. Not required if the target-org configuration variable is already set. |
true | ||
| websocket | option | Websocket host:port for VsCode SFDX Hardis UI integration |
Examples
$ sf hardis:org:diagnose:what-will-break
$ sf hardis:org:diagnose:what-will-break --target-org myorg@example.com
$ sf hardis:org:diagnose:what-will-break --checks legacyApiVersions,releaseUpdates
$ sf hardis:org:diagnose:what-will-break --lookback-days 90 --idle-warning-days 15
$ sf hardis:org:diagnose:what-will-break --ignore-users 'integration@x.com'
$ sf hardis:org:diagnose:what-will-break --agent