My migration is stuck

Symptom: You started a migration from Zendesk, Help Scout, or Intercom, and it has been sitting in the same state for a long time. Maybe stuck at "queued" for over ten minutes. Maybe stuck at "importing" with no progress.

Migrations run on a worker that picks up new jobs every two minutes. A job sitting at "queued" longer than ten minutes is almost always a credential issue, not a backlog.

Checklist

1. Identify the state

Open the migration page and look at the status pill on the failing job.

• Queued means the worker has not started the job. Read step 2.
• Importing with no progress for more than 30 minutes means the worker started but is stalling on a specific page or rate limit. Read step 3.
• Failed means we already know it broke. Read step 4 and check the error.
• Completed with fewer records than expected means the import finished but did not see everything it should have. Read step 5.

2. Queued for too long

If the job has been queued for more than ten minutes, the cause is almost always a credential issue caught at startup.

• Zendesk: the API token has been rotated or the user that owns the token lost agent access. See migrate from Zendesk.
• Intercom: the OAuth grant was revoked. See migrate from Intercom.
• Help Scout: the API key was deleted. See migrate from Help Scout.

Re-enter the credential, save, and the job will pick up on the next worker tick (within two minutes).

3. Importing but not progressing

A long "importing" with no progress usually means upstream rate limiting. Migrations are deliberately polite. We back off when the source platform throttles us.

• Check whether anyone else is using the source platform's API right now (a parallel export, a CRM sync). Pause it and our worker will resume at full speed.
• Some sources cap nightly bandwidth. Resuming the next morning is normal.
• Very large attachments can take a long time per record. The progress bar updates by record, not byte, so a single large record can look like "no progress" for several minutes.

If the job has been at the same record count for over an hour with no source-side activity, treat it as stuck and contact support.

4. Failed jobs

A failed job will show a short error reason. Common ones:

• "Invalid credentials" means the token, key or OAuth grant is bad. Re-enter and retry.
• "Permission denied" means the credential is valid but lacks the scopes we need. Each source's migration article lists the required scopes.
• "Source rate limit exceeded" means we backed off and gave up. Click Retry later in the day.
• "Unexpected source response" is a real bug. Contact us with the job ID.

5. Completed but missing records

If the job says "completed" but you cannot find tickets or customers you expected:

• Check that the completed range covers the time period you wanted. Some sources require date-bounded exports.
• Check that the missing tickets are not filtered out by status. We import open and recently closed tickets by default; very old archived tickets may be skipped.

6. Restart vs resume

Most migrations support resume. Click Retry rather than Restart to pick up where we left off. Restart starts from zero and can create duplicates.

When to contact support

Contact us if:

• A queued job has not moved in 30 minutes after re-entering valid credentials.
• An importing job has not advanced in over an hour with no source-side activity.
• Failed reason is "Unexpected source response".
• Completed counts are wildly off from what you see in the source.

Send the migration job ID, the source platform, and the time the job was started in UTC. See support contact.

Related reading

• Migrate from Zendesk
• Migrate from Intercom
• Migrate from Help Scout