Respond to a failed connector job
When a connector job fails or stalls, the job output almost always tells you what happened. Read it first, then use the tables below to act or route it to the right team.
Routing rule of thumb: problems with the job's settings go to the Builder; problems with connections, agents, drivers, or the relay go to the Administrator.
What this solves
A connector job fails or stalls mid-run, and it's not obvious whether the fix belongs to the operator, the builder, or the administrator. It bounces between teams while the run waits.
Commands and scripts (Run Command, Run Script)
| Output / symptom | Meaning | What to do |
|---|---|---|
| "could not start" / command not found | The program or interpreter isn't on the agent | Builder confirms the command; Administrator confirms it's installed on the agent. |
| Script won't start (PowerShell/Python) | The interpreter isn't installed on the agent | Administrator installs the interpreter (e.g. pwsh, python3). |
| Failed with a non-zero exit code | The command/script reported an error | Builder checks the command and whether Fail on Error, or an exit criterion, should apply. |
| Failed, and the Termination text names an exit criterion or an output parsing rule | The job's configured failure criteria decided the outcome — not the command's exit code on its own | Read the Termination text: it names the rule that fired and the code it set. Builder adjusts the criteria (Run Command / Run Script). |
| Finished OK even though the output looks wrong | Exit criteria are configured and the code resolved to finished OK against them | Builder reviews both halves: the conditions, and the Exit Criteria Result that says whether a match means fail or finish OK. A code matching nothing takes the opposite of that setting, so an over-narrow set lets real failures through. |
| A legacy job finished OK but the agent's own log says it failed | Its criteria table was evaluated by OpCon Continuum rather than by the agent, so the agent was given the platform default and reached the opposite conclusion | Read the Exit criteria evaluated entry in the job's history, which records Finished OK (Exit Criteria) Return Code='N' and names the layer that decided. On a Windows, UNIX/Linux or SQL job the Termination text holds the exit code itself, not that line. Nothing is wrong. |
| A legacy job never starts, and the dispatch is refused on its exit criteria | The relay serving that machine predates Exit Criteria Result, range conditions, or tables of more than five rows, and refuses to send a table it can't represent | Administrator upgrades the relay. As a stopgap, Builder rewrites the table as up to five plain conditions with Exit Criteria Result Fail. |
| Ended after one hour, exit code 128 | The command ran past the fixed one-hour limit every Universal Agent job has, and was stopped | The limit can't be raised. Builder splits the work or makes the command finish within the hour. |
SQL Database jobs
SQL Database Executor jobs do not run in this build. Every one — MS SQL Script, MS SQL Job, MS SQL DTExec, MySQL Script, Oracle Script and Other DB Script on a Universal Agent — fails before it reaches the database:
| Output / symptom | Meaning | What to do |
|---|---|---|
| External plugin sql-executor requires pluginDownloadUrl and pluginChecksum | The agent was not given the SQL Database Executor connector | Nothing in the job or the connection changes this. To run SQL Server scripts today, use the SQL LSAM MS SQL Script job type on a SQL LSAM machine. |
Internal jobs (Null Job, Workflow Container)
| Output / symptom | Meaning | What to do |
|---|---|---|
| Null Job sits waiting | Waiting on its dependencies (by design), or on hold | Operator checks predecessors; release if intentionally on hold. |
| Workflow Container stays running a long time | The embedded (nested) workflow hasn't finished | Open the nested workflow instance and troubleshoot it there. |
| Container failed: "does not exist" / "circular" / "depth exceeded" | The embedded workflow reference is wrong, loops, or nests too deep | Builder fixes the workflow reference. |
| The build succeeded, but a warning says a Workflow Container has no sub-schedule to run | The container couldn't be expanded during the build — the parent still built, by design | Read the reason in the warning (or hover the warning icon on the container job), fix what it names — usually the embedded workflow isn't deployed for that date — then rebuild with overwrite. |
Legacy LSAM commands
| Output / symptom | Meaning | What to do |
|---|---|---|
| "No agent available" | The relay is down or the LSAM machine is unreachable | Administrator checks the relay and LSAM connectivity. |
| Legacy job rejected at dispatch, naming a missing login name, password, user, or group | The batch user connection the job runs as is incomplete | Administrator completes the connection — see Manage connections. |
| Legacy job rejected at dispatch: attached connection is not a … credential | The job's batch user is of the wrong platform's type | Builder re-picks the account in the job's Batch User field. |
| UNIX job rejected at dispatch, naming a missing user or group | A UNIX job must name a batch user, and none is attached | Builder attaches a UNIX Batch User connection. |
| Marked failed though it ran | An exit-criteria condition matched | Builder confirms the failure conditions match the program's real codes. |
A UNIX job ends with exit 127 and the log shows quot: not found (or amp, lt, gt, apos) | An older relay converted the quotes and ampersands in the command into their XML forms, and the UNIX agent ran that text literally | Have the relay upgraded — current relays send UNIX values unaltered. Until then, move the command into a script on the machine and run that. |
A UNIX job is rejected at dispatch naming a field code, for </F> or <F I= | A UNIX value can't carry either sequence — the agent would read it as part of the message rather than as the value | Builder removes it; put those characters in a script on the machine instead. |
| An MS SQL Script job fails reaching the database, after dispatching cleanly | Encrypt Connection is on (the default) and SQL Server has no certificate the machine trusts | Administrator installs a trusted certificate, or the Builder turns Encrypt Connection off. |
| An MS SQL Script job is rejected at dispatch naming its script | Neither SQL Script Statements nor Script File Path is filled in, or both are | Builder supplies exactly one of the two. |
| An MS SQL Script job's own result is ignored | Use Exit Code From Script Result has no effect when the script comes from Script File Path | Builder moves the script inline, or judges the outcome from the reported exit code. |
| Every job on one legacy agent sits Running with no completion, and the agent still reads as reachable | The agent stopped answering without disconnecting — a paused or frozen host, or a NAT port-forward holding the socket open. The relay now declares it down after 90 seconds of an unanswered acknowledgement; on an older relay the wait was about two and a half hours | Confirm the machine is actually up, and have the relay upgraded if it is not declaring the agent down. See When a legacy agent stops answering. |
| A UNIX - File Arrival job is rejected at dispatch naming the file name | The path holds a character the relay refuses anywhere — ``` ` $ " \ ; | & < > ( ) ' ``` — or a space in its directory part, or is over 255 characters. Classic accepts these; Continuum does not, on any agent, because an older UNIX agent hands the name to a shell when it searches |
A UNIX - File Arrival job fails with exit code 2 | The directory being watched does not exist on the agent. Only the file-name part takes wildcards; the directory part is literal and has to be there already | Create the directory on the machine, or correct the path. |
| A File Arrival job watches a day either side of the one you authored | An out-of-date relay sends its own UTC date as the job's schedule date, so the window shifts for agents west of UTC | Have the relay upgraded — see The schedule date a legacy job is sent with. |
File waits
For a Wait for File job that's stuck or timed out, see Respond to a stuck or failed Wait for File job. The job output names the exact criterion it's waiting on.
When you escalate
Include the job output, the job type, and (for database or LSAM jobs) the connection or machine name involved, but never credentials. Note whether the same operation works when run directly (in a terminal, a database client, or on the LSAM machine).
Related topics