Skip to main content

Troubleshooting

1. Agent shows as Offline immediately after registration​

Symptoms: Agent registers successfully, but status shows Offline in the dashboard.

Causes and fixes:

  • The agent process stopped after registration. Ensure the agent is running as a service: migrate-agent start --service (Linux) or check Services / Task Manager (Windows).
  • The machine cannot reach api.theonemigrate.app on port 443. Test: curl https://api.theonemigrate.app/api/health from the agent machine.
  • Firewall or proxy blocking outbound HTTPS. Add an exception for *.theonemigrate.app.
  • Registration code expired (24-hour limit). Generate a new code and re-register.

2. Job stays in "created" status and never starts scanning​

Symptoms: A job was created but the agent never picks it up.

Causes and fixes:

  • The assigned agent is Offline. The start_job command is delivered via the heartbeat, which only happens when the agent is online. Bring the agent online; it will receive the command on the next heartbeat (within 2 minutes).
  • The job was assigned to the wrong agent. Delete the job and create a new one assigned to an online agent.
  • Check agent logs for errors receiving the start_job command.

3. "Azure credentials expired — re-authenticate via dashboard"​

Symptoms: Job fails with this error; project status shows auth_required.

Fix:

  1. Go to the project page.
  2. Click Reconnect Azure Storage.
  3. Sign in with the Microsoft account that has Storage Blob Data Contributor on the storage account.
  4. Save. The project status clears to in_progress.
  5. Create a new job (or re-run the previous one) — completed files do not need to be re-transferred if integrity verification was enabled.

Prevention: Microsoft refresh tokens expire after ~90 days of inactivity. If the migration takes longer than this, reconnect mid-project. The token refresh checker timer warns you by email before expiry.

4. Job fails with "Project has no Azure connection"​

Symptoms: Job status failed with error code NO_AZURE_CONNECTION.

Fix:

  • The project does not have an Azure Storage connection configured.
  • Go to the project → Connect Azure Storage and complete the OAuth flow.
  • Re-create the job.

5. RockRMS connection test fails​

Symptoms: "Test Connection" fails with a SQL Server error.

Diagnosis:

  • Connection refused / timeout: The agent cannot reach the SQL Server. Check:
    • SQL Server name/IP is correct in the connection string.
    • SQL Server has TCP/IP protocol enabled (SQL Server Configuration Manager).
    • Firewall allows the agent's IP to reach the SQL Server on port 1433.
  • Login failed: Credentials are wrong or the SQL account doesn't have read access to the RockRMS database.
  • SSL/certificate error: Add TrustServerCertificate=true to the connection string if using a self-signed cert.
  • Database not found: Verify the database name in the connection string matches the RockRMS database name exactly.

6. RockRMS import has many "errored" records​

Symptoms: Progress shows a high errored count for an entity type.

Common causes:

  • People without names: Records with null FirstName and LastName are imported with placeholder values ("Unknown"). Check if these are real people or RockRMS system records.
  • Invalid emails: Emails that don't match [email protected] format are excluded from the person record (not errored — the person still imports without email).
  • Contribution batch failures: If the Mission API returns an error for a batch (e.g., due to a missing fund or person reference), all records in that batch are counted as errored. Check the Mission API logs for details.
  • Missing person reference in contributions: Contributions without a PersonAliasId are imported with no donor link. These are not errors but will show external_person_id: null in Mission.

7. Financial total doesn't reconcile after RockRMS import​

Symptoms: Post-import verification shows financial_match: false; quality score < 100%.

Causes:

  • The date_range_start filter was set, so only contributions after that date were imported. The Rock total (all time) won't match the Mission total (filtered). This is expected — not a data integrity issue.
  • Contributions flagged as non-positive amounts were still imported but may be causing a total discrepancy. Review the error log for flagged amounts.
  • A contribution batch error caused some transactions to not import. Check the job's error log for batch errors, fix the root cause, and re-run.

8. Transfer speed is very slow​

Symptoms: Job is running but transfer speed is near 0 or very low Mbps.

Checks:

  • Review the project's Bandwidth Schedule — you may be in a throttled window.
  • Check the job's bandwidth_limit_mbps setting.
  • Try increasing Concurrency (default: 4) — more parallel streams can improve throughput on high-latency connections.
  • For large files, increase Chunk size from 8 MB to 32 MB or higher to reduce overhead.
  • Verify the agent machine has adequate outbound bandwidth: run a speed test from the agent machine.
  • Azure storage accounts have per-account egress limits. If multiple jobs are running simultaneously against the same storage account, total throughput is shared.

9. Dashboard shows stale progress after agent reconnects​

Symptoms: An agent went offline and reconnected, but the job progress still shows the old values.

Fix: The progress updates in near-real-time but the dashboard polls every 10 seconds. Wait up to 30 seconds after the agent reconnects for progress to refresh. If progress still doesn't update after 1 minute, check agent logs for errors submitting progress batches.

10. "Registration code already used" or "Registration code expired"​

Symptoms: Running migrate-agent --register <CODE> fails with one of these errors.

Fix:

  • Already used: Registration codes are single-use. If the agent registered successfully the first time (check the Agents list), no action needed. If the agent is not showing up, the code may have been used by a different registration attempt. Generate a new code.
  • Expired: Codes expire after 24 hours. Generate a fresh code and use it immediately.

When to Contact Support​

Self-resolve the issues above first. Contact support if:

  • An agent is online and heartbeating but the start_job command never delivers after 10+ minutes.
  • A job gets stuck in scanning for more than 30 minutes with no progress.
  • The Azure OAuth flow fails after multiple attempts (OAuth token service error).
  • You see unexpected data in Mission after a RockRMS import that doesn't match any known mapping behavior.

Open a support ticket at: [email protected] or via your Hub account → Support.