Errors

A refusal is one sentence that names what to fix. A refused tool call is a tool error, with the sentence in the text, in structuredContent.error and in diagnostics[].message. diagnostics[].code holds a stable code where one is listed below. Wording may change; codes do not. A call outside your scopes is refused as Tools shows. Sign-in, key and GitHub connection failures are on Account errors.

Arguments

Message	Fix
`name the job to submit as deck (a member of the codebase's procedure libraries)`	Pass `deck` to `submit`
`name the transaction to start as transid`	Pass `transid` to `start`
`name the system or a volume (work_id, work_zip_b64), not both`	Give one of `system`, `work_id` and `work_zip_b64`
`a snapshot is laid down on an empty volume: give snapshot_zip_b64 or a volume (work_id, work_zip_b64), not both`	Drop the volume, or the snapshot
`open a unit or a codebase, not both: give unit_zip_b64 or codebase_zip_b64`	Give one
`name the volume to read: work_id, or a system`	Pass `work_id` or `system` to `sql`, `list_datasets` or `read_dataset`
`not a system name: '...' (expected 1 to 63 characters: lowercase letters, digits and '-', a letter or digit first)`	Rename the system or checkpoint label
`no run '...' in this store`	The `work_id` is unknown to your organization. Use one a result of yours returned

Code task-args-too-large: a call made as an MCP task whose arguments pass 8 MB. Send it without the Tasks extension, or name a system or work_id in place of a work_zip_b64.

Zip archives

Code	Cause
`zip-slip`	An entry’s path leaves the directory
`zip-names`	A path appears twice, or a file is also a directory
`zip-members`	Over 50,000 entries
`zip-size`	Over 1 GiB unpacked
`zip-ratio`	A compression ratio over 1000x
`zip-corrupt`	Not a readable zip

Units

Message or sign	Fix
Two demands declared	Keep one of `compile`, `submit` and `CHAIN/chain.json`
An unknown `run.json` key, named	Fix the spelling. See Unit format
A `[site]` key restated in `run.json`	Move it to `harwell.toml`
`not found on the codebase` on a job	The name in `compile` or a deck has no member in the tree. `compile` takes the `PROGRAM-ID`, not the file name. A source file at the top of the tree is not seen: put it in a subdirectory
`seed:` line names a misfit	A fixed-format data set has newlines or a wrong LRECL. Remove the newlines, or declare the right geometry in `CATALOG/_geometry.json`

Codebase refusals

Message	Fix
`this repository needs a credential: sign in as yourself, with GitHub connected; a key acts as nobody on GitHub`	Call as a signed-in person with GitHub connected, or send the tree as `codebase_zip_b64`
`you do not read owner/name on github.com, or it does not exist`	Check the name, and that your GitHub account can read it
`<host> shows this repository to nobody without a credential, or it does not exist; send the directory that holds harwell.toml as codebase_zip_b64`	Send the tree
`<url> redirects, and a redirect is not followed; name the clone URL the repository answers at (many hosts end it in .git)`	Use the exact clone URL
`<host> is not on the public internet; send the tree as codebase_zip_b64`	Send the tree
`owner/name has no ref <ref>; name a branch, a tag or a full commit, and push it first`	Push the ref, or fix it
`owner/name at <ref> holds no harwell.toml in <path>; name the directory that holds it as path`	Fix `path`

A system library bound outside the codebase’s directory is not fetched with it. Send a tree that includes it.

Systems

Code	Message	Fix
`system-busy`	`system '<name>' is busy: <tool> since <time>; call again when it ends`	Wait for the other call to end. `systems` shows it under `busy`
`system-busy`	`system '<name>' is held by terminal <id> ...`	Close the terminal, or `submit` a job, which runs on the terminal’s region
`system`	`no system '<name>' in this store`	Check the name with `systems`
`system`	`system '<name>' has no state yet: run something on it first`	Run a call with `system` first
`system`	`system '<name>' has no checkpoint '<label>'; it has ...`	Use a listed label
`system-stale`	The system moved while this call ran	The run’s volume is kept under the `work_id` the message names. Run again
`system-hold-lost`	The call lost its hold on the system	The run’s volume is kept under the `work_id` the message names. Run again
`system-already-moved`	A task delivered again had already moved the system	Nothing to do: the first delivery’s result stands
`system-holds-unavailable`	Writes to systems are paused for a moment	Call again. Reads still work
`terminal`	The terminal did not answer in time	The system’s state is unchanged. Call again

Inspection

Message	Fix
`a statement here only reads: it starts with ...`	`sql` takes `SELECT`, `WITH` or `VALUES`
`the volume holds no Db2 database: no run on it created a table`	Seed `DB/seed.sql`, or read a volume whose run created tables
`the volume catalogs no data set '<DSN>'; list_datasets names what it holds`	Check the name with `list_datasets`
`<DSN> is a KSDS cluster: ...; REPRO it to a sequential data set in a job to read it here`	`REPRO` it in a job with `return_work`, then read the copy
`name the 01 record in the copybook to read the data set through (record)`	Pass `record` with `copybook`

A failed sql statement returns Db2’s sqlcode and sqlstate: -204 unknown table, -206 unknown column, -104 syntax error.

What a run reports

A run that compiles and executes still fails when a program does. These are reported the way z/OS reports them. For the meaning of a z/OS, CICS or Db2 code, see IBM’s z/OS system codes, CICS abend codes and Db2 SQL codes.

Compile errors

The result opens with the compiler’s first error, at the line in your tree, then the listing with the line marked:

Progs/HELLO.cbl:7: error: 'WS-TOTAL' is not defined
    6 |        PROCEDURE DIVISION.
    7 >            MOVE WS-TOTAL TO WS-COUNT.

A compile is clean when no message has error severity. A listing with only warnings is not a failure.

Steps

A step that worked reads ran or ok in the job log, or cond-bypassed when COND= skipped it. Anything else failed: the step’s first_error and the tail of its output are on the result.

Sign	Cause	Fix
`S806 module(s) not found`	A CALLed program has no source in the tree, under `resolution: "strict"`	Add the program’s source. The clause after the names says whether it is missing or stubbed by policy
`n SQL callees stubbed, no SQL ran`	`sql_callees` is `stub`	Remove the setting to run the SQL
`S722`	A step printed more records than `output_limit`	Raise `output_limit` or add `OUTLIM=`
`STEP-TIMEOUT:`	A step ran past `step_timeout_s`	Look for a loop, or raise `step_timeout_s`
`IEF861I`	A data set the job needs is held by a CICS region	`CEMT SET FILE(x) CLOSED` at the terminal, or wait
A stub listed on the result	A CALL to a program the tree lacks, under `resolution: "authoring"`	Add the program, or set `resolution: "strict"` to fail on it

CICS abends

A condition the program does not handle abends the task with CICS’s code, on the step and in diagnostics with severity abend.

Code	Condition
`AEIM`	`NOTFND`
`AEI9`	`MAPFAIL`
`AEI0`	`PGMIDERR`
`APCT`	`SEND MAP` for a mapset the unit has no BMS source for
`DFHAC2001`	On a terminal screen: a transaction ID outside the region’s PCT

SQLCODEs

Each SQL statement that ended with a negative SQLCODE is a warning in diagnostics (code sqlcode), at the program’s line, with IBM’s text for the codes Db2 defines:

SSYS001.cbl:132: SQLCODE -305 (SQLSTATE 22002) on SELECT ... FROM SYSTEM_PARAMETER: THE NULL VALUE CANNOT BE ASSIGNED TO OUTPUT HOST VARIABLE position-number BECAUSE NO INDICATOR VARIABLE IS SPECIFIED (2 times)

The step’s return code stays the program’s own.

Symbolic map mismatch

A warning (code symbolic-map) when the area a program sends or receives a map from lays out differently from the map assembled from the BMS source. It names the first fields that differ. Remove the hand-written copybook and COPY the mapset.

Oracle misses

With an ORACLE/, the result’s last lines name each item that missed and where it first differs, such as PAY.TOTAL: a and b first differ at record 0, byte 12 of the record. The call is a tool error.

Get started

Guides

Concepts

Reference

Arguments

Zip archives

Units

Codebase refusals

Systems

Inspection

What a run reports

Compile errors

Steps

CICS abends

SQLCODEs

Symbolic map mismatch

Oracle misses

​Arguments

​Zip archives

​Units

​Codebase refusals

​Systems

​Inspection

​What a run reports

​Compile errors

​Steps

​CICS abends

​SQLCODEs

​Symbolic map mismatch

​Oracle misses

Arguments

Zip archives

Units

Codebase refusals

Systems

Inspection

What a run reports

Compile errors

Steps

CICS abends

SQLCODEs

Symbolic map mismatch

Oracle misses