Exit codes and machine messages
- Synopsis
- Full Details
In briefA finished job records an exit code, a termination description and, for a legacy job, an agent message. The exit code is the number the process or agent returned; the termination description says why the job ended; the agent message is a legacy agent's own reason when Termination holds the exit code instead.
WhereProcesses › a job › Summary tab, under Completion: Exit Code, Termination and Agent Message. The job grid and diagram call the exit code Return Code. Past runs are under Status History › Job Execution History, and every run is in Reports › Job History.
When
- A job failed and you need to know why.
- A job went to Initialization Error and never ran.
- You want an event to fire on a particular exit code or reason.
To see how a status is decided, see Job and workflow statuses.
How
- Open the job on Processes and select the Summary tab.
- Read Termination first; on a legacy job, read Agent Message too.
- Look the text up in Termination descriptions to see who fixes it.
- Fix the cause, then restart the job.
The full steps are in Recover a failed run automatically.
- — means no exit code: a job that failed with
0, or one that failed before anything ran. - A process ended by a signal, or by the one-hour limit, reports
128. - Windows, UNIX and SQL legacy jobs record the exit code as their termination description; IBM i
jobs record a message ID such as
SMA0036, SAP R/3 and SAP BW jobs the agent's text, such as0 - 12345601, whose leading code is the exit code, and z/OS jobs the agent's text. - A machine that goes down holds its jobs rather than failing them.
- Every Universal Agent job stops at one hour, whatever it is doing.
- A failure the relay raises before sending a legacy job ends in a code in brackets, such as (RC_NO_RUNAS_LOGIN): restarting without fixing the setting fails the same way.
- An Exit Description event compares the termination description, not the exit code.
Task walkthrough: Recover a failed run automatically. This page is the full reference for what a finished job records about how it ended.
When a job ends, OpCon Continuum records up to three things about how:
- an exit code — the number the process, or the agent, returned;
- a termination description — one line of text saying why the job ended, or, for some legacy jobs, the exit code itself;
- an agent message — a legacy agent's own explanation, kept when the termination description holds the exit code instead.
This page says where each one appears, what Continuum writes there, and what the agents report. How a job's status is decided is on Job and workflow statuses.
- Where You See Them
- Exit Codes
- Termination Descriptions
- Machine and Agent Status
- Troubleshooting
Where You See Them
| Where | What it shows | Labelled |
|---|---|---|
| Processes › a job › Summary tab, Completion section | The exit code, the termination description and the agent message, each only when it has a value | Exit Code, Termination, Agent Message |
| Processes › a job › Output tab | The exit code, or — when there is none | Exit Code |
| The job grid on Processes, and a job's card on the workflow diagram | The exit code | Return Code |
| Status History tab › Job Execution History | One row per past run | Termination Status, Exit Code |
| Job History Detail (a run's Job History Details menu item) › Details | The agent message and the termination description | Agent Message, Termination Description |
| Reports › Job History | A column and a filter for each | Job Termination Status, Exit Code, Termination Description |
| Status History tab | An Exit Criteria Evaluated entry when exit criteria decided the outcome; View details shows the exit code and the verdict | Event, Details |
| An event or a notification | The termination description, through [[JI.$JOB TERMINATION]] | See System properties |
The same number is called Return Code on the grid and the diagram, and Exit Code everywhere else. In the Job History report, a run with no exit code never matches an Exit Code filter, and a run with no termination description matches only Is empty.
No machine message is shown on the Agents page. What an agent's connection is doing is shown only as its status — see Machine and agent status.
Exit Codes
What a blank or a dash means
| You see | Meaning |
|---|---|
| A number | The code the process or the agent returned. 0 normally means success |
| — | No exit code was recorded. A job that failed with exit code 0 shows —, so a failure never reads as 0; so does a failure the platform or relay raised itself, with no process behind it |
| A negative number | A large Windows code, shown in its signed form. For example 0xC000013A is shown as -1073741510. On a UNIX legacy agent, a code of 128 or more also arrives negative unless the agent's LSAM_0_255 option is on; it is off by default |
0 on a UNIX job that was killed | A UNIX legacy agent reports free text such as Killed by Sys Admin in place of the exit code when a job is killed, and Continuum records 0. Read the job's status, not the code |
Universal Agent jobs
Run Command and Run Script record the process's own exit code, with these exceptions:
| Situation | Exit code | Termination |
|---|---|---|
| The process was ended by a signal | 128 — the same as a process that exited 128 | — |
| The job ran for one hour | 128 | Command exceeded its timeout of 3600s and was terminated (or Script …) |
| The agent cancelled the job, for example while shutting down | 128, when the process was ended by the signal | Command was cancelled before completion (or Script …) |
| The command could not be started — for example it does not exist and Run via Shell is off | 1 | The operating system's error text |
| The job definition is not valid | 1 | Invalid task definition: … |
Every Universal Agent job has a fixed one-hour limit; no setting changes it. A timed-out or cancelled job always fails — exit criteria and output parsing are not applied to it.
Exit criteria and output parsing decide what the code means. Output Parsing runs first: the first rule that matches sets the exit code (Exit Code To Set). Exit Criteria then judge that code — a matching row means failure. With no exit criteria, Fail on Error fails any non-zero code; with Fail on Error off, the exit code never fails the job. The exit code recorded is the one after output parsing. A failure's termination text then reads, for example, Exit criteria matched: exit code 5 EQ 5, followed by the error output. Full rules: Deciding success: exit criteria and output parsing.
Wait for File returns 0 when the file is found, and 1 with one of these:
| Termination | When |
|---|---|
Timeout waiting for file: <path> | The hour passed with Fail on Timeout on. With it off, the job finishes OK with 0 |
| File wait cancelled | The agent cancelled the job |
File path '<path>' is outside allowed directories. Allowed: … | The path is not in a folder the agent allows. See Path restrictions |
Null Job and Workflow Container jobs run inside the platform and record no exit code.
Legacy LSAM jobs
A legacy agent decides success or failure itself, from its own job status; the exit code is what it reports alongside.
| Platform | Exit code | Termination |
|---|---|---|
| Windows, SQL | The code the agent reported | The exit code, as text, on success and on failure |
| UNIX/Linux | The code part of the agent's exit status | The exit code, as text, on success and on failure |
| IBM i | 0: the agent reports no numeric code, so a failed run shows — | The message ID the agent reported, such as SMA0036 or SMA0023-CPF0006 |
| SAP R/3 and CRM | The result code at the start of the agent's text — 0, 1, or an agent error code such as 70006. 0 when the text has none | The agent's whole text, such as 0 - 12345601. See What the job reports |
| SAP BW | The result code at the start of the agent's text — 0, 1, or an agent error code such as 70001 | The agent's whole text: 0 - or 1 - and the chain's log ID, or 1 - NOT FOUND. See What the job reports |
| z/OS | 0: the agent reports no numeric code, so a failed run shows — | The agent's text, on success and on failure. See What the job reports |
| Other platforms | 0 | The agent's text |
Because Termination holds the code, the agent's own explanation of a failure goes in the Agent Message row instead. If the job's command line carried an encrypted value, that row reads Agent message withheld — this run's command line carried a secret, because an agent can echo its command line there. See The exit code is also the job's termination description and Summary → Completion carries an Agent Message row.
A failed SAP R/3 or SAP BW job's Agent Message explains its exit code, in plain words, and adds
the agent's own text after a | when that says more than the code — for example The SAP job was
not found, or is not in Scheduled or Ready status. for 70006 on an SAP R/3 Job. The two agents
use some of the same numbers with different meanings, and each job is explained by its own agent's.
When exit criteria decide a job of another type, its termination description reads
Finished OK (Exit Criteria) Return Code='<code>' or Failed (Exit Criteria) Return Code='<code>'.
A failed job that carries the agent's own error message keeps that message instead. A Windows, UNIX
or SQL legacy job keeps its exit code there instead. See
Exit criteria.
Termination Descriptions
Initialization Error
A job goes to Initialization Error when it cannot be sent to an agent at all, or when it was sent and no agent ever picked it up. Nothing ran, so there is no exit code; the termination description says why.
| Termination | Meaning | Who fixes it |
|---|---|---|
Property could not be resolved: <scope>.<name> | A token in a job parameter has no value. See System properties | Builder |
| No date format is defined for property … | A date token with a format suffix, and no global property of that name | Builder |
| Cross-instance addressing is not yet supported: … | A token names another job, schedule or agent | Builder |
No agent pool assigned to job '<job>' | The job has no agent or pool to run on | Builder |
No task definition for job '<job>' | The job has no job-type settings | Builder |
Unknown task type '<type>' - not found in plugin catalog | The job's job type is not installed | Administrator |
No ONLINE legacy-group member with a dispatch pool for job '<job>' | No machine in the job's legacy group can take work | Administrator |
Cannot resolve legacy-group members for job '<job>': … | The group's members could not be read | Administrator |
Cannot resolve script for job '<job>': … | The Run Script job's script could not be found or read | Builder |
Cannot resolve SMAFT file transfer for job '<job>': … | A file transfer's machines or settings could not be worked out | Builder |
Connection instance '<id>' could not be resolved | A connection the job names is missing | Builder |
No agent claimed the job: agent <agent> has been unavailable for 10 minutes | The job was sent, and no agent that could take it was online for 10 minutes. A legacy agent group or a pool reads no agent in group <group> or no agent in pool <pool> has been available. See A job no agent picks up is ended | Administrator |
| No agent claimed the job within 24 hours | The job was sent, and no agent took it within 24 hours | Administrator |
A temporary fault — the property store briefly unreachable, say — does not cause Initialization Error: the job waits and is tried again.
An expression dependency that cannot be evaluated does not fail the job; it puts the job On Hold, with the reason as its termination description, such as The returned value is neither 'True' nor 'False' (expression: …). See Using expressions with dependencies and properties.
Failed — texts Continuum and the relay write
| Termination | Meaning |
|---|---|
Agent execution failed | The agent reported a failure with no reason |
| Work item cancelled in agent-service | The work was cancelled before any agent took it |
| Job failed | A legacy job failed and the agent gave no reason |
| Job not accepted by LSAM | The legacy agent refused the job when it was sent |
Dispatch call timed out after <n>ms | Sending the job to the relay took too long |
No connection to machine <machine> | The relay has no connection to that legacy machine |
| Job not found after agent reconnect | The legacy machine came back, and no longer knows the job |
| Job not found on nudge (LSAM lost track) | While the job was held for a down machine, the machine said it had no such job |
| Held beyond max-hold TTL (machine did not return) | The machine was down for longer than the hold allows — seven days by default. A start that was queued for the machine and never delivered is withdrawn, so the job does not run when the machine returns |
Kill timeout: LSAM did not respond within <n>s after TX0 kill | A Kill was sent and the agent did not report the job ending in time |
| Prerun failed | A legacy job's prerun failed. The job is tried again rather than ended — see A failed prerun is re-attempted, not failed |
A message ending in a code in brackets — … (RC_NO_RUNAS_LOGIN), … (RC_INVALID_SQL_FIELD) —
is the relay refusing a legacy job before sending it, because a setting cannot be expressed to the
agent. The sentence says which setting and why; the job fails with no exit code. Correct the setting
the message names and restart the job.
An OpCon MFT job that ends with a non-zero result fails with MFT run <id> ended with Result
<n>, and its exit code is that result. See OpCon MFT Transfer job.
Machine and Agent Status
A legacy machine's connection messages are not shown to you — not on the job and not on the agent. When a machine goes down, its running jobs are held, not failed, while the relay waits for it to return; when it does, each job is checked again, and only a job the machine no longer knows fails, with one of the texts in the Termination Descriptions tab. See A job always reaches a terminal status.
What you see instead is the agent's status on Agents. Among the labels it shows:
| Status | Meaning |
|---|---|
| Online | The agent, or the legacy machine through its relay, is answering |
| Offline | It has stopped answering, or stopped cleanly |
| Unknown | A legacy machine whose relay is down, so whether it is reachable is not known |
| Marked Offline, Marked Draining | An operator mark you or an event set. Marked Offline always reads alone. When a Marked Draining agent's observed status differs, both are shown, as in Offline (Marked Draining) |
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Return Code shows — on a failed job | The job failed with code 0, or failed before any process ran | Read Termination on the Summary tab |
A Universal Agent job fails at exactly one hour with exit code 128 | The fixed one-hour limit | Split the work into shorter jobs |
Exit code 128 and no timeout message | The process was ended by a signal, or really exited 128 | Check the job output |
| Termination shows only a number on a legacy job | Windows, UNIX and SQL legacy jobs record the exit code there | Read Agent Message for the agent's reason |
| Agent Message reads Agent message withheld … | The job's command line carried an encrypted value | Check the job output on the agent |
| Initialization Error naming a property | A token in a job parameter has no value | Fix the token; see System properties |
| A legacy job fails with a message ending (RC_…) | The relay cannot express a setting to the agent | Correct the setting the message names (Builder) |
| Initialization Error reading No agent claimed the job… | The job's agent, group or pool had no agent online to take it | Bring an agent online, or point the job at one that is, then restart it |
| A job on a down machine stays running | It is held while the machine is away, for up to seven days | Wait for the machine, or cancel the job |
Related topics
- Job and workflow statuses — how a job's status is decided
- Run Command job — exit criteria and output parsing
- Wait for File job — its outcomes
- Legacy LSAM connectors (UNIX/Linux, Windows, IBM i, SQL, SAP R/3, SAP BW, z/OS, MCP and OS 2200) — legacy exit codes and exit criteria
- Workflow events — firing an event on a termination description
- System properties —
$JOB TERMINATIONin an event or notification - Reports — the Job History report