Errors

Errors from MCP tool calls and the CLI carry a stable code your agent can branch on, a human-readable message, and — on demo failures — a remediation field describing what to do next, so failures are machine-actionable rather than English prose to parse.

Error codes

Code	Meaning
`VALIDATION_FAILED`	The request didn’t pass validation.
`TARGET_UNREACHABLE`	The target URL couldn’t be reached — `localhost`/private targets need a tunnel.
`RESET_HOOK_UNVERIFIED`	The environment’s reset hook didn’t respond during creation; pass `skipResetVerification: true` to bypass.
`SESSION_STATE_INVALID`	The uploaded session data was malformed or empty.
`ENVIRONMENT_SESSION_MISSING`	A demo referenced an environment with no captured session.
`UNAUTHORIZED`	Missing, invalid, or revoked credentials.
`MAGIC_LINK_INVALID`	Expired or already-used magic-link token.
`LOGIN_CODE_INVALID`	Expired, already-used, or unknown pairing code.
`FORBIDDEN`	Authenticated, but not allowed to access this resource.
`NOT_FOUND`	Resource doesn’t exist (or isn’t yours).
`MAGIC_LINK_ALREADY_SENT`	A magic-link request is already pending for this email.
`INSUFFICIENT_CREDITS`	Not enough credit balance to start a demo.
`CONCURRENCY_LIMIT_REACHED`	Too many demos running at once for your plan.
`BILLING_NOT_CONFIGURED`	Billing isn’t set up for this account.
`INTERNAL_ERROR`	Unexpected server error.

Demo-failure codes

Returned in failure.code on a finished-but-unsuccessful demo — the request itself succeeded, but the demo couldn’t complete:

Code	Meaning
`SESSION_REQUIRED`	The environment needs a session and none is captured — create a pairing code and run `director session`.
`SESSION_EXPIRED`	The captured session aged past `sessionLineageMaxAgeMs` or a re-check found it stale — recapture it.
`SESSION_REJECTED`	Verification actively failed (e.g. redirected to a login page) — recapture the session.

Run director doctor if you’re not sure whether a problem is your setup or something on Director’s end — it checks your credentials, environment, and whether Director itself is reachable.

Getting Started

Concepts

Reference

Error codes

Demo-failure codes

​Error codes

​Demo-failure codes

Error codes

Demo-failure codes