When a run stops

What a stop means

When a required source has no row the contract can admit, the run stops. It names the reason, writes no file and exits with 2. Nothing half-written is left behind: the old result file, if any, is untouched.

$ observatory run observatory.yaml --out out/observatory.sqlite
error: Run blocked (required_source_has_no_admissible_evidence);
  refusing to create artifact …/out/observatory.sqlite
$ echo $?
2

Check and correct the input

1. Run observatory validate --config observatory.yaml from the configuration folder.
2. Find the named source and read its status and first reported reason.
3. Check the source path and required columns. For renamed headers, review the field mapping; for rejected records, inspect the source row and reason.
4. Correct the source data or its declared mapping, then validate again. Keep missing evidence missing rather than filling it with guessed values.
5. Run the Engine again once the blocking issue is resolved. Check the new result with observatory-reader out/observatory.sqlite --check before opening it.

Do not change a source to optional merely to silence a failure. Required and optional sources describe which evidence the run needs.

Understand the validation exit code

observatory validate shows each source before you run: its status, how many rows it accepted and rejected, and a note. Validation exits with 2 when a source is neither ACCEPTED nor SKIPPED, unless it failed with required: false and another analytical source supplied admitted rows. A non-zero row_residual also causes exit 2: the physical row count does not equal accepted plus rejected plus skipped rows. Rejected rows alone are not a validation failure.

Read the warning

For timestamp errors, start with invalid timestamps or end before start. For omitted columns, read unmapped input columns. Every warning and what to do about it is listed under Warnings. Exit codes are defined with the commands.