Error Diagnostics

Error Diagnostics

z-fasta reports command failures on stderr with stable symbolic codes and observed facts. Successful FASTA, FAI and statistics output stays on stdout. Validation findings go to stdout; with --json they use the envelope described here, with its validation field filled.

Choose a renderer

z-fasta get --error-format=json genome.fa chr1:1-100
z-fasta --error-format=text stats genome.fa

The default is --error-format=text. The exact alternatives are --error-format=text and --error-format=json; the space-separated form is not accepted. The option can precede the command or appear among its arguments. The last valid repetition wins. Values of --names, --bed, -o, --schema, --custom-alphabet and --max-header-len remain option values even if their bytes resemble a renderer option.

Help and version retain their position-dependent behavior. An invalid renderer option uses a short text fallback and exit 1. Failure while allocating command arguments also uses text. A broken stderr sink can prevent any report from arriving. A reader that closes stdout early ends any command with exit 141 and no report, as SIGPIPE would. A consumer must handle missing JSON as a failure to obtain a report.

Text and machine examples

Running z-fasta get returns exit 1, empty stdout and:

error [usage.missing_argument] get: A required argument is missing. argument=fasta_path
hint: Correct the command arguments; use --help for accepted options.

Running z-fasta get --error-format=json returns exit 1 and one newline-terminated JSON object on stderr. This excerpt comes from that report; the complete object also includes validation, sources, outputs, metrics and action:

{
  "catalog_revision": "0.4.0-1",
  "producer": {
    "name": "z-fasta",
    "version": "0.4.0"
  },
  "kind": "failure",
  "operation": {
    "name": "get",
    "complete": false,
    "work_complete": false
  },
  "accepted": false,
  "failure": {
    "primary": {
      "code": "usage.missing_argument",
      "category": "usage",
      "severity": "error",
      "kind": "failure",
      "unit": "none",
      "stage": "arguments",
      "source": null,
      "location": {
        "offset": null,
        "line": null,
        "column": null
      },
      "record": null,
      "request": null,
      "related": [],
      "cause": null,
      "data": {
        "argument": "fasta_path"
      }
    },
    "secondary": [],
    "secondary_truncated": false
  }
}

Read failure.primary.code, not the English message or the numeric Zig error tag. The primary records the selected condition; failure.secondary retains up to two later failures, such as failed cleanup or reporting. secondary_truncated says whether more secondary failures were omitted.

Interpret the report

catalog_revision identifies the code definitions (0.4.0-1 for this catalog), and producer.version identifies the executable. They are separate values. Preserve unknown codes and fields when forwarding a report; do not turn an unknown code into success or infer a retry policy from its category or suggested action.

operation.work_complete records whether the command's work finished. operation.complete also requires its required side effects to finish. accepted cannot be true for incomplete work or a blocking failure. A failed notice can therefore return exit 1 after data has already reached stdout.

outputs describes stdout, a requested file or caller writer, and stderr separately. States are not_started, staged, published, streaming, unknown or aborted. records counts records completed by the writer. logical_bytes counts bytes accepted by the writer, including buffered bytes. Neither proves the visible prefix is complete. may_be_partial marks a possible prefix, and final_flush is not_attempted, succeeded or failed. The serialized object cannot certify its own final stderr flush. Always check the actual process status and whether the full JSON object arrived.

Source IDs name roles within this command: FASTA, the selected sidecar, names or BED input, stdout, stderr, requested output, or a temporary spool. Their labels can be truncated; an unavailable label or location stays null. Derived sidecar labels use the original FASTA path and suffix. Offsets are zero-based byte offsets; lines, byte columns, records and requests are one-based original positions, not slots in a retained array. A code's unit describes the reported condition, not an occurrence count or a promise that every location is known.

Integers wider than 32 bits are decimal strings, including lengths, offsets, ordinals, timestamps and GET summary metrics. Small integers such as a byte value, format version or flags remain JSON numbers. Missing observations are null. An exact measurement uses its ordinary field; an observed lower bound uses a _min field. Do not read a lower bound as an exact count.

Opaque paths, identifiers and byte previews use an object with encoding, value, truncated and either original_bytes or observed_bytes_min. Valid UTF-8 uses encoding: utf8; other bytes use encoding: base64. Decode according to that field. A truncated preview is only the retained prefix, even after decoding. Native causes retain the observed Zig name or native domain and number; no missing errno is guessed.

Keep status, data and reports together

This shell job retains failure evidence and publishes extracted data only after exit 0:

work=$(mktemp -d)
status=0
z-fasta get --error-format=json genome.fa chr1:1-100 > "$work/result.fa" 2> "$work/report.json" || status=$?
if [ "$status" -ne 0 ]; then
    printf 'GET failed with exit %s; files retained in %s\n' "$status" "$work" >&2
    exit "$status"
fi
mv "$work/result.fa" result.fa
rm -r "$work"

GET can write earlier valid records before a later request fails. Do not publish its temporary stdout file merely because it is non-empty. Ordinary successful machine-mode commands need not emit a stderr report. get --summary --error-format=json requests a summary envelope with decimal-string region_count, total_bases and elapsed_ns; its successful FASTA still goes to stdout.

Validate needs a separate policy: exit 0 means no findings, exit 2 means warnings only, and exit 1 means errors, strict warning rejection, an unfinished report, or an operational failure. With --json, stdout is one envelope whose validation holds the findings: read validation.outcome, validation.completion and accepted together with the status. Allow exit 2 only if your job explicitly permits warnings. A report whose completion is interrupted also fills failure, and the same failure goes to stderr in the format --error-format selects. See Validation and repair for counting and repair rules.

A local consumer example in tests/consumer_json.sh exercises these policies, including missing and truncated JSON. It does not establish integration with a workflow scheduler, HTTP service or telemetry system.

Native callers

Core command functions return a finite diagnostics.Error!T and fill an explicit caller-owned diagnostics.Failure. They return after releasing their working resources. They do not select a renderer or terminate the process. Multiple codes share a Zig error tag, so handle the tag for propagation and inspect the captured code and facts for the exact reason.

tests/consumer_commands.zig is a compiled example using the existing command exports. It handles a missing file and an overlong path from each of index, GET, stats and validate, then successfully calls each again without running the CLI dispatcher. Run it with zig build test-diagnostics. These are internal command APIs, not a newly published stable FASTA library.

Failure construction allocates no message or growing chain. It retains previews in a shared 256-byte pool, up to two secondary diagnostics, and 16 source roles. Borrowed labels must live through handling or the next reset. Preview views borrow the owning Failure until reset or overwrite. A validator Report is a fixed-size value that copies its first-occurrence identifiers; Report.validation returns a view that borrows the report. These storage limits do not bound the validator's duplicate check, which grows with the number of distinct identifiers.

See For contributors for the source owners and checks.

Active code catalog

The registry contains 111 codes. This list gives each code's kind, its unit when it is a finding, and its native detail fields from diagnostics.Details; shared stage, source, location, record, request, related and cause sit outside those fields. The FASTA, header, sequence and format findings are what the validation report counts, in the listed units; four of them also describe repair blockers. With validate --index, the report also counts the six pair.* codes that compare records with the index: for pair.record_missing_from_fasta, record is the entry's number in the index. Every code has error severity except the warnings fasta.empty_record, fasta.long_header, header.convention_mismatch and the six format.* codes.

The machine renderer preserves the native fields with these explicit conversions:

• io.unexpected_eof uses read_kind plus the selected read's fields.
• index.unsupported_version uses found_version and supported_versions.
• index.not_found uses attempted_formats and attempted_sources.
• repair.blocked uses reason_code, the selected blocker fields and repair_policy.
• Argument sets become arrays of selected argument names. Temporary attempts become entries plus truncated. Byte previews and exact/lower-bound measurements follow the encodings above.

A field ending in offset or describing a byte extent refers to bytes in its named source. Lengths and start/end fields identify the sequence or coordinate system named in that code's data. Expected/found values retain the original check's values. Null fields mean unobserved facts, not zero. The typed definitions and renderer are the source of field types and nested shapes.

• usage
  • usage.command_required: failure; no fields.
  • usage.unknown_command: failure; fields command.
  • usage.unknown_option: failure; fields option.
  • usage.missing_argument: failure; fields argument.
  • usage.extra_argument: failure; fields argument, allowed_count.
  • usage.missing_option_value: failure; fields option, expected.
  • usage.repeated_option: failure; fields option.
  • usage.conflicting_options: failure; fields arguments.
  • usage.option_requires: failure; fields option, required.
  • usage.invalid_option_value: failure; fields option, expected, value.
• io
  • io.file_not_found: failure; no fields.
  • io.access_denied: failure; no fields.
  • io.invalid_path: failure; fields reason, limit_bytes.
  • io.open_failed: failure; no fields.
  • io.stat_failed: failure; no fields.
  • io.read_failed: failure; fields requested_bytes.
  • io.unexpected_eof: failure; fields exact, delimiter.
  • io.map_failed: failure; fields map_bytes.
  • io.create_failed: failure; no fields.
  • io.write_failed: failure; no fields.
  • io.flush_failed: failure; no fields.
  • io.publish_failed: failure; no fields.
  • io.temp_unavailable: failure; fields purpose, attempts.
  • io.cleanup_failed: failure; fields resource_role.
• resource
  • resource.out_of_memory: failure; fields allocation_role, requested_bytes.
  • resource.capacity_limit_exceeded: failure; fields capacity_role, limit, required.
  • resource.count_overflow: failure; fields counter, max_value, current, increment.
  • resource.line_buffer_exceeded: failure; fields buffer_bytes, observed_bytes.
• input
  • input.changed: failure; fields changed_fields, before, after, disappeared.
  • input.unsupported_format: failure; fields detected.
• fasta
  • fasta.no_records: finding per file; no fields.
  • fasta.content_before_header: finding per line; fields content_bytes.
  • fasta.header_control_byte: finding per byte; fields byte, grammar.
  • fasta.sequence_control_byte: finding per byte; fields byte, grammar.
  • fasta.empty_record: finding per record; no fields.
  • fasta.empty_identifier: finding per record; no fields.
  • fasta.duplicate_identifier: finding per record; fields identifier.
  • fasta.identifier_too_long: finding per record; fields observed_bytes, limit_bytes.
  • fasta.long_header: finding per record; fields observed_bytes, limit_bytes.
• header
  • header.convention_mismatch: finding per record; fields convention.
• sequence
  • sequence.invalid_symbol: finding per byte; fields byte, policy.
• format
  • format.sequence_whitespace: finding per line; fields whitespace_bytes.
  • format.blank_sequence_line: finding per line; no fields.
  • format.inconsistent_wrapping: finding per record; fields expected_width, actual_width.
  • format.leading_bom: finding per file; no fields.
  • format.missing_terminal_newline: finding per file; no fields.
  • format.mixed_line_endings: finding per file; no fields.
• index
  • index.initial_header_required: finding per file; fields byte, required_offset.
  • index.no_indexable_records: finding per file; no fields.
  • index.identifier_too_long: finding per record; fields observed_bytes, limit_bytes, format.
  • index.sequence_line_too_long: finding per line; fields field, observed, limit, width_role, format.
  • index.record_count_limit_exceeded: finding per file; fields record_count, max_records, format, limit_role.
  • index.side_table_offset_limit_exceeded: finding per record; fields offset, max_offset, offset_role.
  • index.source_timestamp_out_of_range: finding per file; fields timestamp_ns, min_ns, max_ns.
  • index.nonuniform_fai: finding per record; fields reason, expected, observed.
  • index.not_found: failure; fields zfi_source, fai_source.
  • index.no_records: finding per file; fields format.
  • index.invalid_magic: finding per file; fields expected_magic, actual.
  • index.unsupported_version: finding per file; fields found_version, supported_version.
  • index.truncated: finding per file; fields section, required_end, available_end.
  • index.name_footer_missing: finding per file; no fields.
  • index.name_table_invalid: finding per file; fields slot.
  • index.name_blob_out_of_bounds: finding per file; fields name_blob_bytes, payload_end, records_end.
  • index.name_out_of_bounds: finding per record; fields name_offset, name_bytes, blob_bytes.
  • index.zero_sequence_length: finding per record; fields sequence_length.
  • index.invalid_line_geometry: finding per record; fields geometry, constraint.
  • index.sequence_offset_out_of_bounds: finding per record; fields sequence_offset, source_bytes.
  • index.sequence_span_out_of_bounds: finding per record; fields required_end, source_bytes, entry.
  • index.arithmetic_overflow: finding per field; fields field, arithmetic, lhs, rhs, max_value.
  • index.fai.field_missing: finding per field; fields field, column_number.
  • index.fai.invalid_integer: finding per field; fields field, value.
  • index.fai.integer_out_of_range: finding per field; fields field, max_value, value.
  • index.side_table_offset_out_of_bounds: finding per record; fields offset, region_start, region_end.
  • index.side_table_misaligned: finding per record; fields offset, alignment_bytes, section.
  • index.side_table_empty: finding per record; fields line_count.
  • index.side_table_order_invalid: finding per record; fields table_start, minimum_start.
  • index.side_base_start_mismatch: finding per record; fields entry, base_start, expected_base_start.
  • index.side_line_geometry_invalid: finding per record; fields entry, geometry, constraint.
  • index.side_first_offset_mismatch: finding per record; fields first_byte_offset, sequence_offset.
  • index.side_line_order_invalid: finding per record; fields entry, byte_offset, minimum_offset.
  • index.side_sequence_length_mismatch: finding per record; fields indexed_length, side_table_bases.
  • index.older_than_source: finding per file; fields index_mtime_ns, source_mtime_ns.
  • index.source_size_mismatch: finding per file; fields stored_bytes, actual_bytes.
  • index.source_mtime_mismatch: finding per file; fields stored_mtime_ns, actual_mtime_ns.
• pair
  • pair.region_length_mismatch: finding per record; fields requested_symbols, observed_symbols, interval, examined_span.
  • pair.total_length_mismatch: finding per file; fields indexed_total, observed_total.
  • pair.record_missing_from_index: finding per record; no fields.
  • pair.record_missing_from_fasta: finding per record; no fields.
  • pair.sequence_length_mismatch: finding per record; fields indexed_length, observed_length.
  • pair.sequence_offset_mismatch: finding per record; fields indexed_offset, observed_offset.
  • pair.line_geometry_mismatch: finding per record; fields indexed_line_bases, indexed_line_bytes, indexed_layout, observed_line_bases, observed_line_bytes, observed_layout.
  • pair.side_table_mismatch: finding per record; fields indexed_lines, observed_lines, line.
• request
  • request.no_regions: failure; fields request_source.
  • request.sequence_not_found: failure; fields lookup_scope, index_source, identifier.
  • request.start_before_one: failure; fields start, coordinate_system.
  • request.start_after_sequence: failure; fields start, sequence_length.
  • request.end_before_start: failure; fields start, end.
  • request.end_after_sequence: failure; fields end, sequence_length.
  • request.ordinal_out_of_range: failure; fields ordinal, record_count.
  • request.output_buffer_too_small: failure; fields required_bytes, available_bytes.
  • request.identifier_too_long: failure; fields identifier_bytes, limit_bytes.
  • request.bed.field_missing: failure; fields field, column_number.
  • request.bed.invalid_coordinate: failure; fields field, coordinate_system, value.
  • request.bed.coordinate_out_of_range: failure; fields field, max_value, coordinate_system, value.
  • request.bed.invalid_interval: failure; fields start, end, coordinate_system.
  • request.bed.invalid_strand: failure; fields strand, accepted.
• transform
  • transform.complement_on_protein: failure; fields transform, classification, sample, identifier.
• repair
  • repair.output_is_input: failure; fields input, output, comparison.
  • repair.output_identity_unknown: failure; fields input, output.
  • repair.blocked: failure; fields blocker, repair_policy.
• internal
  • internal.consistency_failed: failure; fields component, check.