Errors

The envelope

Every failure surfaces as a message of type: "error":

{
  "type": "error",
  "message": "human-readable summary",
  "code": "one of the eight codes below",
  "phase": "parse | execute | python",
  "traceback": "full Python/Q# diagnostic",
  "framework": "qiskit | cirq | cuda-q | qsharp",
  "dependency": "missing package name"
}

type and message are always present. code and phase are present on every execution-path error (parse/execute/run_python). traceback, framework, and dependency are included only when set — absent keys, not null. Hardware and protocol-level errors carry only type and message (see below).

An error never terminates a sequence by itself: parse errors follow the (null) snapshot, execute errors are followed by result: null, and run_python errors are followed by python_result — orderings are specified in execution messages.

A replay-tested example:

parse_syntax_error_qiskit.request.json

{
  "type": "parse",
  "code": "from qiskit import QuantumCircuit\nqc = QuantumCircuit(2\n",
  "language": "python"
}

parse_syntax_error_qiskit.responses.json

[
  {
    "type": "snapshot",
    "data": null
  },
  {
    "type": "error",
    "message": "SyntaxError: '(' was never closed",
    "code": "compile_error",
    "phase": "parse",
    "traceback": "<any>",
    "framework": "qiskit"
  }
]

Error codes

All eight codes, when they fire, which optional fields they carry, and how to recover. Source of truth: kernel/executor.py and kernel/adapters/qsharp_adapter.py.

Code	Fires when	Extra fields	Recovery
unsupported_framework	No detection regex matched the code (and no language hint resolved it). Message: "No supported quantum framework detected in code."	—	Add a framework import (from qiskit import ...), or send the language field.
missing_dependency	The framework’s adapter (or a framework module the user’s code imports) isn’t installed: adapter import failed, an ImportError escaped an adapter, or the user-code traceback ends in ModuleNotFoundError for one of the framework’s own packages.	framework, dependency	Install the package named in dependency (qiskit, qiskit_aer, cirq, cudaq, qdk).
compile_error	Python SyntaxError/IndentationError in user code, or the Q# compiler rejected the source.	traceback, framework	Fix the source; message is the compiler’s one-line summary, traceback the full diagnostic.
execution_error	User code raised any other exception; a Q# program failed at runtime; or shots was not a positive integer for a Q# run. Also the generic fallback for unexpected source-mode failures.	traceback (usually), framework	A user-code bug — read the traceback. Any output/stderr printed before the failure was still delivered.
no_circuit	execute only: the framework loaded and the code ran, but no circuit object was defined (Q#: no zero-parameter operation entry point). parse reports the same situation as snapshot: null with no error.	framework	Define a Qiskit QuantumCircuit, Cirq Circuit, CUDA-Q kernel — or for Q#, a zero-parameter operation like operation Main() : Result[].
adapter_error	The circuit existed but the kernel failed to convert it into a snapshot (find_circuit/extract_snapshot raised; Q# circuit-JSON conversion failed).	traceback, framework	Usually an unsupported construct or a kernel bug — file an issue with the traceback.
simulation_error	Snapshot extraction succeeded but the simulator raised. The sequence still includes the (non-null) snapshot before the error.	traceback, framework	Circuit may exceed the simulator’s reach (qubit count, unsupported op). The diagram is still valid.
timeout	Two cases. Q# (watchdog, fires in production): a Q# request exceeded its budget — 30 s for parse/QIR compile, 300 s for execute. qdk has no cancellation, so the runaway program keeps the dedicated interpreter thread busy; until it finishes (or the kernel restarts), further Q# requests fail fast with this same code and a “previous Q# run is still occupying the interpreter” message. Python frameworks: user code exceeded 30 s — only when the Executor runs on a process’s main thread (SIGALRM-based); the production server executes on worker threads, so this never fires over the WebSocket.	framework (Q# case)	Q#: check for infinite loops, then restart the kernel — the interpreter stays wedged until restart (or until the runaway run finishes on its own). Python: only reachable when embedding kernel.executor.Executor directly; split the workload.

The no_circuit shape, replay-tested (note the error → result: null ordering):

execute_no_circuit.responses.json

[
  {
    "type": "snapshot",
    "data": null
  },
  {
    "type": "error",
    "message": "No quantum circuit found in code.",
    "code": "no_circuit",
    "phase": "execute",
    "framework": "qiskit"
  },
  {
    "type": "result",
    "data": null
  }
]

Protocol-level errors

Two failures occur before any handler logic, and carry only message:

Trigger	Message
Frame is not valid JSON	"Invalid JSON"
Unrecognized request type	"Unknown message type: <type>"

unknown_message_type.request.json

{
  "type": "bogus"
}

unknown_message_type.responses.json

[
  {
    "type": "error",
    "message": "Unknown message type: bogus"
  }
]

The hardware error convention

hardware_* handlers do not use error codes or phases. When one raises, the reply is a bare envelope whose message is prefixed by the failing operation:

Request	Message prefix
hardware_connect	Hardware connect failed:
hardware_set_credentials	Hardware set-credentials failed:
hardware_clear_credentials	Hardware clear-credentials failed:
hardware_connected_providers	Failed to list connected providers:
hardware_list_jobs	Failed to list jobs:
hardware_list_backends	Failed to list backends:
hardware_submit	Hardware submit failed:
hardware_status	Job status lookup failed:
hardware_results	Failed to get results:
hardware_cancel	Cancel failed:

Two hardware failure modes deliberately do not use the envelope, so clients get structured data instead of a string:

• Provider-side submit failures can return a hardware_job_submitted carrying a "status": "failed" job — see hardware messages.
• Unknown job ids on hardware_status/hardware_results return synthesized stale payloads — see hardware messages.