> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metaphi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every refusal Harwell gives and how to fix it, and the codes a run reports.

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](https://docs.metaphi.ai/harwell/tools.md#scopes) shows. Sign-in, key and GitHub connection failures are on [Account errors](https://docs.metaphi.ai/account/errors.md).

## 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](https://docs.metaphi.ai/harwell/unit-format.md) |
| 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](https://docs.metaphi.ai/account/github.md), 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](https://www.ibm.com/docs/en/zos/3.1.0?topic=zos-mvs-system-codes), [CICS abend codes](https://www.ibm.com/docs/en/cics-ts/6.x?topic=diagnostics-transaction-abend-codes) and [Db2 SQL codes](https://www.ibm.com/docs/en/db2-for-zos/13.0.0?topic=codes-sql).

### Compile errors

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

```text theme={"dark"}
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:

```text theme={"dark"}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.