MetaLens360Help Center

Troubleshoot sync failures

Find out why a sync failed or got stuck, what each Sync Center error message means, and the quickest fix for each one.

Updated in Troubleshooting

Overview

Most sync problems fall into four groups: the org's credentials were refused, the sync was interrupted, Salesforce returned nothing, or a sync was already running. The good news: a failed sync never damages what you already have. When a run fails, MetaLens360 leaves the existing metadata in place, so your pages keep showing the last good copy.

Before you start

  • You need the Run sync on demand permission (sync.run) to retry syncs — every built-in role except Viewer.
  • Know where to look: the Recent Sync Runs table at the bottom of the Sync Center. Hover over a Failed chip to read the full error.

Steps

  1. Open Sync Center and look for a red banner at the top. "N org(s) cannot sync — Salesforce refused the stored credentials" means the problem is credentials — click Open Connections and follow Fix expired org credentials.
  2. Check the org's status chip: Reconnect needed, Syncing, Queued or Not synced.
  3. In Recent Sync Runs, hover over the Failed chip for the error message.
  4. Match the message to the table below and apply the fix.
  5. Retry with Re-sync. If the same failure repeats, try Force Full Resync.
Message (start)What happenedFix
"The sync worker never started (queued N min ago)"The run waited in the queue and no worker picked it upRun it again
"The sync process stopped responding N min ago — sync interrupted"The run stalled mid-wayRun it again; use Selective for large orgs
"Server restarted — sync interrupted"The service restarted during the runRun it again
"Fast sync retrieved 0 files for <org> … Existing metadata left intact (no swap)."Salesforce returned nothing — usually an authentication or session problemTest and reconnect the org
"Incremental sync failed for <org> (existing metadata left intact): …"The incremental run hit an errorRead the rest of the message; then Force Full Resync
"Retrieve returned 0 components for <org>."The full retrieve came back emptyTest the connection; check the user's metadata access

Example

Priya's nightly schedule shows acme-dev Failed with "Fast sync retrieved 0 files for acme-dev — likely authentication or session error." She clicks Test on the Connections page and gets "The saved Salesforce session was rejected". The org had been added with an access token. She reconnects it with SFDX Auth URL, and the next Re-sync completes.

FAQs

Will a failed sync delete my data?

No. Failed runs leave the previous metadata intact. Deleting run history doesn't touch metadata either.

Why can't I start a second sync for an org?

You'll see "<org> is already syncing or queued. Wait for it to complete." Only one sync per org can run at a time. Sync All Orgs skips orgs that are already busy.

Where can I see failures over several days?

Use Activity Timeline on Org Sync & Repo Fetch Status and filter to Org sync.

Troubleshooting

The sync completed, but analysis pages are empty

The sync succeeded but the index may not have. See Pages show no data.

Syncs fail every night at the same time

Look for an expired credential, or two schedules competing for the same orgs. Overlapping schedules are blocked on save, but check Syncs at Once isn't higher than your org can handle.

A large org always times out

Split the work: run Selective syncs for groups of types (for example Code & Automation, then Schema), or lower Syncs at Once in the schedule so fewer orgs run together.

A sync button is disabled or shows a permission error

A disabled button usually means the org is already syncing or queued. "Your role does not have permission to do this (sync.run)" means your role can't run syncs — Viewers can't by default. See Permission denied errors.

Was this article helpful?

Related articles