Errors

A diagnostic names where reading failed and the reader-spec statement that was active. Start with the message, then compare the marked input with that statement. The first visible mismatch may come from an earlier wrong count or an extra token consumed in a previous record.

Follow a real check failure

This reader checks that each job uses every machine once:

site/examples/tutorial/jobshop-checks.iris

n_jobs: 1..
n_machines: 1..
check n_jobs <= (gecode.int_max - 2) / 2 / n_machines "there are too many jobs and machines"
repeat n_jobs as jobs {
  each job
  repeat n_machines as steps {
    each step
    machine: 0..<n_machines
    duration: 0..
  }
}
check distinct(job.machine) "a job uses a machine twice; each job must use every machine once"
check sum(j in jobs: sum(j.duration)) <= gecode.int_max "the total duration is too large"

The first job below uses machine 0 twice:

site/examples/guides/jobshop-invalid.txt

2 2
0 3 0 2
1 4 0 1

iris read site/examples/tutorial/jobshop-checks.iris site/examples/guides/jobshop-invalid.txt --dzn

site/examples/guides/jobshop-invalid.txt:2:1: check failed for record 1 of 'jobs': a job uses a machine twice; each job must use every machine once
     2 | 0 3 0 2
       | ^
spec: site/examples/tutorial/jobshop-checks.iris:12

Read the diagnostic in three parts:

• The first line gives the input path, line and byte column, then the message.
• The excerpt and caret mark the input position. A record check uses the saved record start, so the caret can precede the duplicate token itself.
• spec: gives the reader-spec path and active statement’s line. An active while reading: context, when present, identifies repeats, sections or fields.

Columns count UTF-8 bytes. Control characters are escaped and long excerpts are cut. A caret marks a position; it does not always cover the whole bad token. Record numbers in diagnostic messages start at 1.

Find the stable error code

The iris command prints a human-readable diagnostic, without an error code. --json selects data output on success; it does not change errors into JSON. Build the conformance driver to get a canonical error document for the same failing read. Put iris-driver on your PATH alongside iris:

iris-driver read site/examples/tutorial/jobshop-checks.iris site/examples/guides/jobshop-invalid.txt

{"code":"E-CHECK-FAILED","message":"check failed for record 1 of 'jobs': a job uses a machine twice; each job must use every machine once","input_location":{"origin":"site/examples/guides/jobshop-invalid.txt","line":2,"column":1},"spec_location":{"origin":"site/examples/tutorial/jobshop-checks.iris","line":12,"column":null},"context":null,"record_path":[0]}

The code is E-CHECK-FAILED. record_path: [0] identifies the first job using indices from 0. The input and reader-spec locations have separate fields. Canonical documents are defined in the data model; location profiles and error ordering are in the errors chapter.

Separate source errors from reading errors

iris check parses and resolves a reader spec without reading input. Syntax, reading-type and placement errors point into that source. Expressions still execute at read time: a misspelled value name can pass check and later report E-NAME-UNDEFINED.

For reading errors, check the input shape first:

• E-EXPECTED-VALUE: the token cannot be read using the required type. Check earlier counts if the token belongs to a later section.
• A range rejection also uses E-EXPECTED-VALUE. Check the input’s numbering base and the reader’s bounds.
• E-LINE-MATCH: compare literal text, punctuation and captures, or look for a missing required sections arm.
• E-TRAILING-INPUT: data remains after the reader ends. Check counts and trailers before ignoring it.
• E-BUDGET: inspect repeated work; see performance.

A failed read exits with status 1 and prints no partial data. CLI usage errors exit with status 2. Error codes identify language failures and are separate from those process exit statuses. See the CLI guide for command modes.