Overview
When you run a Data Bridge agent command, it finishes with an exit code that tells you whether it succeeded and, if not, what went wrong. This article lists the exit codes and the most common problems, with how to fix them.
User Roles
This feature can be used by:
- Centre Manager
Exit Codes
| Code | Name | What it means |
|---|---|---|
| 0 | Success | The command completed with no errors. |
| 1 | Partial success | The run completed but some records failed (or a schema check found critical drift). Check the summary and logs. |
| 2 | Configuration error | The agent is not registered, or its configuration is missing or invalid. Run register, then validate. |
| 3 | Source connectivity failure | Could not connect to your source database. Check the connection string and that the machine can reach the database. |
| 4 | Portal connectivity failure | Could not reach the portal. Check the portal URL, that outbound HTTPS is allowed, and that the API key has not been revoked. |
| 6 | Lock conflict | Another run for the same job (or write-back for the same source system) is already running. Wait for it to finish, or stagger your schedule. |
| 7 | Write-back execution failure | A live write-back ran but at least one change failed to apply. Check the logs for the failing change IDs. |
| 8 | Job inactive | The job has been switched off in the portal. Nothing was read or written. |
| 99 | Unhandled error | Something unexpected happened. Check the log file and raise a support ticket with the details. |
Common Problems
"Agent is not registered. Run 'register' first."
- Cause: No stored configuration was found at the config path — the agent hasn't been registered on this machine, or a different
--config-pathwas used when registering. - Fix: Run
registeron this machine. If you keep the configuration in a custom location, pass the same--config-pathto every command.
"Another sync for job N is already running." (exit code 6)
- Cause: A previous run of the same job is still in progress, or a crashed run briefly held the lock.
- Fix: Wait for the current run to finish. If you schedule syncs, make sure the same job can't be scheduled to overlap itself.
Source connectivity failure (exit code 3)
- Cause: The connection string is wrong, the SQL Server is unreachable from this machine, or a firewall is blocking it.
- Fix: Re-run
registerto re-enter the connection string, and confirm the machine can reach the database (host, port, credentials, firewall).validatechecks this quickly.
Portal connectivity failure (exit code 4)
- Cause: The portal URL is wrong, outbound HTTPS is blocked, or the agent API key has been revoked in the portal.
- Fix: Check the portal URL and that outbound port 443 is allowed. If the key was revoked, regenerate it on the Agents page and re-run
register.
Tips & Notes
- Your database credentials and API key never appear in the logs. Record data does — entries are labelled with the record's MIS ID, and validation failures quote the failing value, so you can find the row.
- Record-level failures and validation messages are also shown against the run in the portal, under Execution results.
- When raising a support ticket, include the relevant log lines and the exit code.
Terminology
The terminology used in this article may differ depending on your Centre's configuration.
Related Articles
- Registering and Running the Data Bridge Agent
- Understanding Sync Jobs in Data Bridge
- Understanding Validation Rules in Data Bridge
Need Help?
If you need assistance, please contact Onefile Support or your internal support team.