Errors and recovery

An error is not automatically an agent failure. Validation can reject a recipe before work starts; execution can finish while assessment is unavailable; a network failure can leave an acknowledgement uncertain.

Read the diagnostic

CLI JSON, TypeScript FiredrillError.toJSON(), and Python FiredrillError.to_dict() expose the same diagnostic concepts:

Field	Meaning
`code`, `category`	Stable failure identity and classification
`message`, `repair`	What happened and the next action
`workStarted`	`true`, `false`, or `"unknown"`; never assume false
`uncertain`	Whether an action’s acknowledgement is unconfirmed
`retry`	`never`, `same_request`, or `reconcile`
`operationId`, `batchId`, `runId`	Available saved recovery/inspection handles
`requestId`	Service request identity, when available
`validation`	Structured input diagnostics, when applicable

Keep diagnostics and private journals protected. Do not log raw recipes, application outputs, credentials, or configuration merely to explain a failure.

Catch typed errors

TypeScript
Python

FiredrillError is exported by @firedrill-run/sdk:

import { FiredrillError } from "@firedrill-run/sdk";

try {
  await client.simulate(recipe, target);
} catch (error) {
  if (!(error instanceof FiredrillError)) throw error;
  const diagnostic = error.toJSON().error;
  console.error(diagnostic.code, diagnostic.repair);
  // Preserve diagnostic.operationId and the private journal.
  // Do not automatically start a new simulation.
}

from firedrill import FiredrillError

try:
    result = client.simulate(recipe, target)
except FiredrillError as error:
    diagnostic = error.to_dict()["error"]
    print(diagnostic["code"], diagnostic["repair"])
    # Preserve operationId and the private journal.
    # Do not automatically start a new simulation.

The snippets wrap your existing client, recipe, and actual application target.

Choose the matching recovery action

Situation	Action
Invalid input, work not started	Repair the named input, then deliberately submit
Read-only transport failure	Repeat the same read with the same selection/cursor
Uncertain queue-only submission	Reconcile its original submission key
Interrupted or uncertain execution	Resume its original execution operation ID and journal
Assessment unavailable or failed	Inspect assessment history; explicitly reassess frozen evidence if needed
Missing/expired/deleted evidence	Inspect available lifecycle metadata; do not invent output or rerun to conceal the gap

CLI examples, using actual returned handles:

firedrill submit --resume SUBMISSION_KEY --json --non-interactive
firedrill simulate --resume OPERATION_ID --json --non-interactive
firedrill follow BATCH_ID --json --non-interactive
firedrill lifecycle BATCH_ID --json --non-interactive

Execution resume can dispatch unfinished target work; follow only observes. A submission key is not an execution operation ID. Reuse the original account, project/environment, recipe intent, and private journal. Do not switch identity or create a new key to bypass an uncertain action.

Authentication and scope

An explicit FIREDRILL_TOKEN takes precedence over protected interactive login. If it fails, clients do not borrow another identity. SCOPE_CONFLICT means your selected project/environment disagrees across sources; select one consistent pair. FD_SDK_IDENTITY_CHANGED means the protected login changed while a client was active. Verify the intended identity and create a new client deliberately; recover previous work with its original identity. Firedrill selects its service address automatically. FD_API_ENDPOINT_LOCKED rejects custom endpoint settings before network access. Do not edit a saved recovery journal’s origin.

Assessment is separate

A completed execution may have no requested assessment, a partial assessment, or an evaluator error. Missing evidence is not zero and an evaluator outage is not a failed agent. A required gate can be inconclusive; a simulation without a gate is not_configured. See the CLI exit-code reference when integrating with CI.

​Read the diagnostic

​Catch typed errors

​Choose the matching recovery action

​Authentication and scope

​Assessment is separate

Read the diagnostic

Catch typed errors

Choose the matching recovery action

Authentication and scope

Assessment is separate