MetaLens360Help Center

Fix expired org credentials

When an org shows Reconnect needed, Salesforce has refused its stored credentials. Re-credential it in place from the Edit dialog without losing any synced data.

Updated in Troubleshooting

Overview

MetaLens360 checks an org's credentials every time it syncs or you click Test. If Salesforce refuses them — the session expired, the token was revoked, or the login is no longer valid — the org is marked and shows a red Reconnect needed chip. Hovering over it explains why and says "This org cannot sync until it is reconnected — open it and sign in again."

You'll also notice:

  • A red banner in the Sync Center: "N org(s) cannot sync — Salesforce refused the stored credentials", with an Open Connections button.
  • An email to workspace admins, "Action needed: MetaLens360 cannot reach <org>", sent on the first failure and then at most once a week while it stays broken.

The fix is to re-credential the org. Its history and synced metadata stay attached.

Before you start

  • You need the Manage org/Git connections permission (Admin, Architect and DevOps by default).
  • You need a Salesforce login for the org, or a new SFDX Auth URL from the Salesforce CLI.

Steps

  1. Open Connections and find the org with Reconnect needed.
  2. Click Reconnect (or the edit icon). The Edit Org Connection — <org> dialog opens.
  3. Under Credentials, choose a method:
    • Sign in with Salesforce (recommended). For a sandbox, enter test.salesforce.com in Login domain (optional); for My Domain, enter that host. Leave it blank for production. Click Sign in with Salesforce, log in and approve.
    • SFDX Auth URL. Log in with the Salesforce CLI, run sf org display --target-org myorg --verbose --json, paste the sfdxAuthUrl value and click Save Changes.
    • Access token — only as a stopgap; it expires again within hours.
  4. Back on the page, click Test. "Connection verified!" means you're done.
  5. The chip turns green after the next successful authentication. Run a sync from the Sync Center to catch up on missed changes.

Example

Overnight syncs for acme-uat started failing after the sandbox was refreshed. Priya gets the "Action needed" email, opens the org, chooses Sign in with Salesforce, enters test.salesforce.com as the login domain and signs in. Test shows "Connection verified!", and she clicks Re-sync in the Sync Center.

FAQs

Why does this keep happening to the same org?

It was probably added with an access token, which has no refresh token. The Edit dialog warns "This connection will keep expiring". Switch it to Sign in with Salesforce or SFDX Auth URL to fix it permanently.

What commonly invalidates credentials?

A sandbox refresh or clone, a password change or connected-app policy that revokes tokens, an admin revoking access in Salesforce, or logging in on the wrong host (production vs sandbox vs My Domain).

Can I change who receives the email?

Admins can adjust it in the Communication Center under the "Org connection needs re-authorisation" email.

Do I lose my data when reconnecting?

No. Reconnecting updates the existing connection in place.

Troubleshooting

"The saved Salesforce session was rejected (HTTP 401) — it has likely expired."

The stored session is no longer valid. Reconnect with Sign in with Salesforce or SFDX Auth URL.

"This org has no usable credentials stored."

Nothing usable is saved for the org. Provide new credentials through the Edit dialog.

Sign-in succeeds but the org is still refused

You may have logged in to a different org. Check the login domain — sandboxes use test.salesforce.com or their My Domain host.

"Login URL must be a Salesforce domain"

Enter only a Salesforce host in Login domain (optional), with no path.

Was this article helpful?

Related articles