Skip to main content

Errors and diagnostics

Rank prefers explicit diagnostics over coercions, silent fallbacks, or partial output. Most failures fit into a small set of stages.

Where errors happen​

Parse and resolution​

These failures happen before type checking:

  • syntax errors
  • unresolved names
  • invalid imports
  • module cycles

Type checking and annotations​

These failures happen once the compiler can analyze program structure:

  • type mismatches
  • invalid collection or object shapes
  • bad @constraint, @unique, or @sensitive usage
  • invariant violations such as duplicate @unique values

Use rank check <entry> to catch this entire class without evaluating external inputs.

Evaluation and external inputs​

These failures happen only when the program is actually evaluated:

  • missing or invalid Env<T> inputs
  • HTTP::Fetch cache or schema mismatches
  • provider invocation failures
  • invalid Emit::manifest(...) entries
  • path normalization and path escape errors

Use bare rank <entry> when you need to exercise these runtime-like evaluation steps.

Host workflow errors​

Some errors are about how the CLI command is used rather than the Rank value itself:

  • --file-root used with a non-manifest result
  • serve-only entrypoints used with the wrong command
  • output materialization paths that resolve outside the chosen root

Common categories​

  • Type and shape errors — the value does not match its declared or inferred type.
  • Annotation errors — an annotation is unknown, misplaced, malformed, or its invariant evaluates to false.
  • External input errors — environment variables, HTTP responses, files, or providers do not satisfy the declared schema.
  • Output manifest errors — duplicate paths, unsupported formats, or mismatched payloads such as non-string text values in Emit::manifest(...) entries.
  • Path errors — invalid relative paths, upward traversal, or boundary violations while applying a manifest.

Sensitive values​

Use @sensitive on bindings that should be redacted in diagnostics:

@sensitive
api_key = Env<Object { API_KEY: string, ...: string }> {}.API_KEY

When a diagnostic renders that binding, Rank shows <sensitive> instead of the real value.

Practical workflow​

  1. Run rank check <entry> first for syntax, import, type, and annotation problems.
  2. Run rank <entry> when you need to validate environment inputs, providers, HTTP fetches, or output manifests.
  3. Use rank test <path> when you want to pin either expected output or expected diagnostics in a repeatable suite.