Diagnostics reference

The structured error shape shared by the Rust crate and the TypeScript runtime.

Compilation, Contract validation, provenance validation and host-value validation all fail the same way: with a list of structured items rather than a string. One serializable type, Diagnostic, backs all four. The outer error types stay domain-specific for Rust ergonomics — CompileError.diagnostics, ContractValidationError.violations, HostValueValidationError.violations — but the items are the same algebra, and ContractViolation and HostValueViolation are type aliases for Diagnostic. The TypeScript runtime deliberately reproduces the same serialized item shape, so a consumer that already reads candid-core violations reads those too.

Three failures sit outside that shape, all of them at a decode boundary before validation begins, and each is named below: JSON that is not well formed at all (ContractJsonError::MalformedJson, which carries the serde message as a plain string), host value JSON decoding, and a rejected portable limits configuration.

The fields of a diagnostic#

pub struct Diagnostic {
    pub code: String,
    pub phase: Option<DiagnosticPhase>,
    pub severity: Option<Severity>,
    pub path: Option<String>,
    pub message: String,
    pub span: Option<SourceSpan>,
    pub related: Vec<RelatedLocation>,
    pub notes: Vec<String>,
    pub resource_limit: Option<ResourceLimitInfo>,
}

Every optional field is omitted from JSON when absent, so each domain has a predictable serialized shape: a compile diagnostic is {code, phase, severity, message, span?, related?, notes?, resource_limit?}, and a validation violation built in the validation domain is {code, path, message, resource_limit?} — it can also carry span, related and notes when it arrived by conversion from a compile diagnostic, which is lossless for those fields. All the item types deserialize with unknown keys rejected.

Spans: exact, or source-scoped#

A SourceSpan carries source_name, start_byte and end_byte. One rule governs the combinations: the two offsets are set together or not at all, and a span must name a source, carry offsets, or both. Deserialization rejects a half-span (one offset without the other) and a fully empty span, which leaves three legal forms and two kinds.

{ "source_name": "memory:/lib.did", "start_byte": 3, "end_byte": 4 }
{ "source_name": "memory:/lib.did" }
{ "start_byte": 3, "end_byte": 4 }

The first and third are exact: offsets that are genuinely valid for the source's original text. The source name is optional there — compile_did omits it on a type-check failure, where the offsets index the one source it was handed. The second is source-scoped: it names a logical source and withholds offsets. That form exists because the native compiler backend type-checks by materializing pretty-printed copies of sources into a private temp directory, and offsets against that rewritten text would be wrong for the user's file. They are withheld rather than published as if exact. Not leaking the temp directory, the numeric materialized file name, or a rewritten offset dressed up as an original one is the design intent, and the test suite asserts it case by case — see tests/diagnostics_contract.rs and tests/browser_wasm.rs — rather than by a proof over all inputs.

start_byte and end_byte are fixed-width u64 on the wire, so the same span serializes to the same numeric text on every platform. A consumer that indexes text with them must narrow with a checked conversion.

ResourceLimitInfo#

pub struct ResourceLimitInfo {
    pub resource: String,
    pub limit: u64,
    pub observed: u64,
}

Attached to every resource_limit_exceeded failure and to nothing else. limit and observed are fixed-width u64 for the same platform-neutrality reason. The resource string is not the Limits field name: the field max_input_bytes reports as input_bytes, max_value_depth as value_depth. Some resources are charged by more than one limit, and extension_bytes has no field of its own — it is charged against max_value_bytes. Match the resource string as data; do not assume a max_<resource> field exists. The Limits reference maps every one.

The triple survives every domain crossing verbatim. When a Contract validation failure converts into a compile diagnostic during lowering, or a compile diagnostic converts into a violation during provenance rederivation, the code, path, span, related locations, notes and resource metadata all travel item by item. No path in the crate reduces a resource failure to message text.

{
  "code": "resource_limit_exceeded",
  "path": "$.value.value.value.value",
  "message": "value depth exceeds limit 3",
  "resource_limit": { "resource": "value_depth", "limit": 3, "observed": 4 }
}

The same failure in the compile domain gains phase and severity:

{
  "code": "resource_limit_exceeded",
  "phase": "lower",
  "severity": "error",
  "path": "$",
  "message": "$: resource canonicalization_work exceeded limit 1; observed 2",
  "resource_limit": { "resource": "canonicalization_work", "limit": 1, "observed": 2 }
}

The stable code list#

Every code below is a literal string in the repository's own source. They are grouped by where they come from, not by how they are spelled.

Operational: budget, cancellation, deadline#

These three cover every budget failure, in every domain.

Contract document: markers, identities, declarations#

Contract type graph#

Envelope and serialization#

Provenance sidecar#

These fire when a SourceInfo arrives from outside and is checked against a recompilation of its own embedded sources.

Compilation#

Compile items always carry phase and severity. Four codes are the generic per-phase fallback; the rest are specific.

Resolvers#

A resolver's ResolveError reaches the caller as a load-phase compile diagnostic carrying these codes.

Host values#

Value violations always carry path and never carry phase or severity, so they serialize as {code, path, message, resource_limit?}.

Not diagnostics: the limits configuration errors#

A rejected portable limits configuration returns a LimitsConfigError, which carries code(), path() and message() and displays as {code} at {path}: {message}. It is a separate type, but the same stability rule applies to its three codes: unsupported_limits_version at $.version, unsupported_limits_profile at $.profile, and limit_override_unrepresentable at $.overrides.<field>.

Emitted only by the command-line binary#

Reading a failure in Rust#

use candid_core::{Contract, Limits, RuntimeContext};

let context = RuntimeContext::new(Limits::default().with_max_input_bytes(64));
match Contract::from_slice_with_context(document, &context) {
    Ok(contract) => println!("{}", contract.contract_id()),
    Err(candid_core::ContractJsonError::MalformedJson(message)) => {
        eprintln!("not a Contract document: {message}");
    }
    Err(candid_core::ContractJsonError::InvalidContract(error)) => {
        for violation in &error.violations {
            // `code` and `path` are the stable surface; `message` is not.
            eprint!("{} at {}", violation.code, violation.path.as_deref().unwrap_or("$"));
            if let Some(info) = &violation.resource_limit {
                eprint!(" [{} limit {} observed {}]", info.resource, info.limit, info.observed);
            }
            eprintln!();
        }
    }
}

The TypeScript side#

@candid-core/schema reproduces the same serialized item shape on purpose. Its issue interfaces carry exactly { code, path, message, resource_limit? }, its codes are stable snake_case strings, and its paths are $-rooted with .name for ASCII-identifier-shaped keys and ["…"] or [3] otherwise — the same $.declarations[3].name style candid-core emits.

export interface ValidationIssue {
  readonly code: ValidationCode;
  /** `$`-rooted path to the offending value, candid-core style. */
  readonly path: string;
  readonly message: string;
  readonly resource_limit?: ResourceLimitInfo;
}

export type ValidateResult =
  { readonly ok: true } | { readonly ok: false; readonly issues: readonly ValidationIssue[] };

Where the two agree#

• The item shape, key for key, including the optional resource_limit triple.
• $-rooted structured paths, and the same stability boundary: codes and paths are the interface, message text is not.
• resource_limit_exceeded is spelled identically and carries the same {resource, limit, observed}, with value_depth and value_elements as shared resource names.
• Ten codes in the runtime's Contract loader are the Rust ones verbatim: unsupported_contract_format, unsupported_format_version, unsupported_semantics_profile, unsupported_canonicalization_profile, dangling_type_ref, duplicate_field_id, empty_declaration_name, duplicate_declaration_name, invalid_extension_name, resource_limit_exceeded.
• Both fail closed and neither repairs input.

Where they differ#

• No phase, severity, span, related or notes. The runtime has no compiler and no source text, so an issue is the four-key form and nothing more.
• Codes are closed TypeScript unions. ValidationCode, CodecCode and ContractIssueCode are union types, so adding a code is an API change you see at compile time. Rust codes are plain strings.
• No exceptions for control flow. validate, encode, decode and schemaFromContract return { ok: true, … } | { ok: false, issues } and never throw on the value or document they are given — a value that fights inspection with a throwing accessor or a hostile Proxy produces a terminal unreadable_value issue instead. Data never throws. Passing the wrong schema does: resolveSchema, serviceMethods, and unwrapResult raise a TypeError eagerly, which is a programmer error rather than a failure mode. So does passing the wrong options: every entry point above throws TypeError for an unknown option key or a limit that is not a non-negative safe integer, before it reads anything — the TypeScript counterpart of the Rust policy's refusal of unknown override fields.
• No sentinel on the issue cap. Rust replaces the last slot with a resource_limit_exceeded sentinel; the TypeScript walk's maxIssues (default 100) stops collecting, and the result is still not-ok.
• Some resource names have no Rust counterpart — the codec's bytes, type_table_entries and numeric_bytes, the loader's name_table_entries, which bounds a caller-supplied field-name table that has no candid-core equivalent, and stack, reported by validate, encode and decode when the host JavaScript stack runs out — in code a walk calls (a getter, a rec thunk), since the walks themselves are iterative.

The three TypeScript code sets#

There is no code for opt opt, opt null or opt reserved: both the loader and the generator accept them and box their present values as { some: v }. See Candid to TypeScript mapping.

import { validate } from "@candid-core/schema/validate";
import { Account } from "./ledger.ts";

declare const incoming: unknown; // a value you were handed

const result = validate(Account, incoming);
if (!result.ok) {
  for (const issue of result.issues) {
    // Same rule as in Rust: match `code`, read `path`, display `message`.
    console.error(`${issue.code} at ${issue.path}`, issue.resource_limit ?? "");
  }
}

Next#

Edit this page on GitHub