Error reference

What a failed run prints, and what to do about it: reading the traceback, Qiskit provider errors, IonQ API responses, and IonQ job failures.

Errors reach you from four places: your own Python, the Qiskit provider that talks to IonQ, IonQ's service, and the playground itself.

Start with the traceback

A failed run prints a Python traceback into the run console, in red. The last line names the exception and its message; the lines above it name the file and the line number that raised it.

Every backend behaves this way: one handler serves the browser simulators, the IonQ remote simulators and IonQ hardware. The runtime drops its own internal frames from the traceback, shortens package paths and corrects the line numbers back to the lines you wrote. The exception and its message reach you unchanged.

When the failure came back from IonQ, the IonQ error name is inside the exception message, as a word in CamelCase: CompilationError, NotEnoughQubits, TooManyGates. Read the last line of the traceback, find a name of that shape, and look it up in Job failures on IonQ backends below.

A traceback with no such name is a Python error raised by your code or by Qiskit; fix the line it names. One exception: an AttributeError raised inside qiskit-ionq means the job did reach IonQ and the provider dropped the name while parsing the reply. See Errors from the Qiskit provider.

The console shows one run at a time. To keep a traceback, copy it with the toolbar's copy button before you run again.

Failures in your browser

The local simulators (the built-in one, the AWS Braket local simulator and the IBM noise models) run in the browser tab and never submit a job, so an IonQ code cannot appear. Their errors are Python exceptions from your own code or from Qiskit.

A browser run is free, so run there first to rule out your own code. See Compute backends for which entries in the Select QPU dialog run locally.

The playground also raises a few messages of its own, before any backend is involved:

Symptom	What to do
A red traceback with no `CamelCase` IonQ name in it	A Python error from your code or from Qiskit. Fix the line the traceback names and run again.
JSPI compatibility warning	Your browser does not support JSPI. The FAQ lists browsers that do.
"Can't run quantum jobs as an anonymous user at the moment"	The run was refused before it reached a backend. Sign in again, then rerun.
Out of credits	See How credits work.
"only one job is allowed per code run"	Your code sent a second job to an IonQ backend in the same run. Pass every circuit to one `backend.run` call, or press Stop and then Run. See One job per run on IonQ.
"network access is restricted"	Your code sent a request other than GET or OPTIONS, which the runtime blocks. See Network access.

Errors from the Qiskit provider

qiskit-ionq is the client library between your code and IonQ. It sits in front of every IonQ backend, so the case below can occur on the free remote simulators as well as on hardware.

The known case is an AttributeError raised inside qiskit-ionq while a job is being submitted. Quantum Garden's author traced it: the provider crashes parsing an IonQ error response that arrived as a plain string rather than an object. Its own failure then replaces IonQ's message, so the original cause never reaches you. Quantum Garden's author says the underlying error is usually an auth failure or a quota issue, so check credits first.

Quantum Garden handles it in published code:

quantum_garden.py Python · excerptOpen in Playground ↗

  try:
    job = backend.run(circuit, shots=shots)
  except AttributeError as e:
    # qiskit-ionq bug: SDK crashes parsing error responses that are
    # plain strings instead of dicts. The real error is usually
    # an auth failure or quota issue.
    print(f"qiskit-ionq SDK parsing bug — check API key and backend target: {e}")
    return
  except Exception as e:
    print(f"Job submission failed: {e}")
    return

▶ Run on QollabBackend

The general defence is wrapping the submit call in try. Entangled Body's three-tier fallback is a worked example.

API responses from IonQ

These are transport-level failures, raised before any circuit is executed. They apply to every run that leaves your browser, so a free remote simulator can return them as well as hardware.

On Qollab the IonQ API key belongs to the platform, so IonQ's advice to check or rotate your key does not apply: a 401 or 403 cannot be fixed from your side. When a row says to report it, use Share feedback, pick Bug Report, and attach the project so the run can be traced.

Status	What it means and what to do
`400 Bad Request`	The request was malformed, and IonQ's message names the parameter it rejected. Read that name out of the traceback, then check the argument you passed for it, most often `shots` or a gate argument.
`401 Unauthorized`	The API key failed to authenticate. It is the platform's key, not yours, so nothing on your side can rotate it. Report it through Share feedback.
`403 Forbidden`	The key authenticated and was then refused that resource. Nothing in your circuit causes this. Report it through Share feedback.
`404 Not Found`	The job or backend IonQ was asked for does not exist. Report it through Share feedback with the project attached.
`429 Too Many Requests`	The request was rate limited. Retry shortly. The key belongs to Qollab rather than to you, so report a repeat through Share feedback rather than contacting IonQ.
`500 Internal Server Error`	A service was offline, unavailable, or failed in a way IonQ could not attribute. Check status.ionq.co and retry.
`502 Bad Gateway`	A misbehaving proxy or a service issue. IonQ says these can be retried. Check status.ionq.co.
`503 Service Unavailable`	A service outage. Check status.ionq.co and retry.

Job failures on IonQ backends

A job that was accepted and then failed returns one of these twenty names. The groups follow the stage IonQ's own description names for each code. IonQ does not publish which codes a noise-model simulator can produce, so the groups below are by stage, not by backend.

Validation and compilation

IonQ checks and rewrites every job before it is targeted, so this group is reachable on a free remote simulator as well as on hardware. It is also the group a circuit that grew during transpilation lands in. See How your circuit is compiled for why the gate count you wrote is not the one submitted.

Code	What it means and what to do
`PreflightError`	A preflight check failed, most often because the circuit was syntax checked and found to hold malformed gates, commands or formats. It was caught before anything ran, so it cost nothing. The built-in simulator catches the same class of problem instantly.
`InvalidInput`	The job input failed validation, and IonQ's message names the part that was invalid. Usually a gate argument the backend will not take.
`CompilationError`	A generic failure inside IonQ's compilation service. Run the same circuit on the built-in simulator first. If it passes there, simplify it and resubmit.
`OptimizationError`	A generic failure inside IonQ's optimization service. Retry once, then simplify the circuit.
`NotEnoughQubits`	The backend has fewer qubits than the job requires. Check the qubit column on Compute backends, then pick a bigger backend or shrink the circuit. A Forte remote simulator stops at 29 qubits where the hardware has 36.
`TooManyGates`	The job has more gates per circuit than the target backend allows. Transpiling adds gates, so the count you wrote is not the count submitted.
`TooManyShots`	The job asked for more shots than the target backend allows. Lower the `shots` argument on your run.
`TooManyControls`	A multi-control gate carried more control qubits than allowed, which IonQ caps at seven. Decompose it into smaller gates.
`UnsupportedGate`	The job uses a gate the target backend does not allow. Transpile for the target, or swap the gate. See How your circuit is compiled, and the Gate reference for the standard gates and IonQ's native ones.
`TooLongPredictedExecutionTime`	The predicted execution time ran longer than that backend's single-job timeout. Lower `shots` first, since runtime scales with it.

IonQ's simulation service

These two come from the remote simulators, the free IonQ backends in the Select QPU dialog.

Code	What it means and what to do
`SimulationError`	A generic failure inside IonQ's simulation service. That is their cloud simulator, not the local one, so try the built-in simulator that runs in your browser.
`SimulationTimeout`	The simulation ran past IonQ's runaway process timeout, most commonly because it was too large for the service. Use fewer qubits or fewer shots, or a local simulator. Noise-model simulation runs one simulation per shot, so the shot count is the fastest lever.

On the quantum computer

These describe a job that reached real hardware.

Code	What it means and what to do
`QuantumComputerError`	A generic failure while the job was being processed on the QPU. It reached the machine and failed there. Retry, and report it through Share feedback if credits were spent.
`QuantumCircuitComplexityError`	The coherent program for this circuit cannot feasibly run on the system targeted. IonQ says reducing the number of gates often resolves it. The other option is a simulator, where depth is not limited by coherence.
`DebiasingError`	An execution error while using debiasing, IonQ's own error mitigation. Debiasing is on by default only at 500 shots or more and cannot run below that. The backend default of 1024 clears the floor, so a job meets it unless your code asks for fewer. See Error mitigation and debiasing.

Billing and service

Nothing in your circuit produces these.

Code	What it means and what to do
`QuotaExhaustedError`	The billing system shows an inadequate credit balance for the job. See How credits work.
`ContractExpiredError`	The contract governing the API key has expired. That is the platform's IonQ contract rather than your account, and nothing in the editor can fix it. Report it through Share feedback.
`UnknownBillingError`	An error related to, but not originating from, IonQ's billing service. Usually a brief outage. Retry.
`InternalError`	An internal error IonQ could not attribute. Retry once. If it repeats, check status.ionq.co.
`SystemCancel`	IonQ staff cancelled the job by hand, usually at a customer's request and sometimes to resolve an unknown failure. Nothing in your circuit caused it. Resubmit.

Stay in the loop.

Get the latest tutorials, demos, and project showcases straight to your inbox. No noise, just the good stuff.

Enable JavaScript to sign up.

Qollab updates only. Unsubscribe any time. Privacy Policy.