Troubleshooting
Every error in Synchronoid has a code that starts with SYN-. Find the code in the run page, in an alert or in the CLI output, and use this page to find the likely cause and the fix.
Error codes
| Code | Meaning | Likely cause and fix |
|---|---|---|
SYN-1042 | Source request timed out | The provider is slow or unreachable. The step is retried. If it keeps happening, raise the timeout or check the provider status page. |
SYN-1051 | Provider rejected credentials (401 or 403) | The token has expired or lost access. Update it with syn secrets set. See Secrets. |
SYN-1060 | Source paused automatically | Too many failures in the time window. Fix the cause, then run syn sources resume NAME. |
SYN-2104 | Waited too long for request budget | The source budget is used up. Lower concurrency, raise max_wait or reduce backfill load. See Rate limits. |
SYN-2110 | Provider returned 429 | Another system may share the key. Lower per_minute, and check the Retry-After setting. |
SYN-3012 | Secret or environment value not found | The name has no value in this environment. Run syn secrets list --env prod and set it. |
SYN-3020 | Invalid synchronoid.yaml | Run syn deploy --dry-run. The message shows the line. Unknown keys are errors. |
SYN-3101 | Step returned invalid records | A record is missing the merge key or has a wrong type. Check the step output in the run page. |
SYN-3140 | Step is not idempotent | A replay produced different output for the same input. Remove clock reads and random values. See Retries and replays. |
SYN-3201 | Raw data expired | The payload is older than the retention period. Replay from the source instead of --from-layer raw. |
SYN-4010 | Invalid API token | The token is missing, revoked or from another workspace. Create a new one in the control room. |
SYN-4290 | API rate limit exceeded | Wait for Retry-After. See the REST API reference. |
SYN-5001 | Internal error | Not caused by your project. Retry, and contact support with the request_id if it persists. |
Common problems
"Not signed in" or 401 in CI
In CI, set the SYN_TOKEN environment variable. The CLI does not open a browser when this variable is set. In a terminal without a browser, use syn login --no-browser.
Certificate errors behind a company proxy
If your network inspects TLS traffic, the CLI may fail with a certificate error. Point it to your company certificate file:
$ export SYN_CA_BUNDLE=/etc/ssl/company-ca.pem $ syn doctor
syn dev does not show my asset
Check that the package that contains it is listed under modules in synchronoid.yaml, and that the decorator is @sy.asset. The local control room is at localhost:4040. Local data lives in .synchronoid/, and you can delete that folder to start clean.
A schedule did not run
Run syn schedules list. A schedule can be disabled, its source can be paused, or the previous run may still be active when max_concurrent_runs is 1. Check on_missed to decide what happens after an outage.
A webhook is not received
Open Change feeds in the control room and look at the delivery log. Common causes are a response that takes more than 10 seconds, a non-2xx status, or a failing signature check because the body was parsed before verification. See Change feeds.
Backfill is slower than expected
The request budget of the source sets the limit, not the number of workers. Run syn backfill ... --dry-run to see the earliest finish time. See Backfills.
Collect diagnostics
syn doctor checks the CLI and SDK versions, Python version, token, network access to api.synchronoid.com and the project file.
$ syn doctor OK syn 0.14.2 (sdk 0.14.2, python 3.12.4) OK token valid for workspace acme-data OK api.synchronoid.com reachable (42 ms) FAIL synchronoid.yaml: unknown key "retires" on line 14 (SYN-3020) $ syn doctor --bundle Wrote syn-diagnostics-20261029.zip
The bundle contains versions, redacted configuration, recent CLI logs and the ids of recent runs. Secret values and record data are never included. Read the file before you send it, if you like.
Run the CLI with -vThe verbose flag prints every HTTP request and its request_id. This helps us find the exact request on our side.
Contact support
Use the contact form and include:
- The error code and, if you have one, the run id or
request_id. - What you expected and what happened.
- The diagnostics bundle from
syn doctor --bundle. - The time the problem started, with time zone.
Explorer plans get community support. Team plans get email support, and Enterprise plans have a named engineer. To check whether the platform has a known issue, see the status page.