When a Qiskit circuit produces an unexpected result, the problem is often not the quantum algorithm itself. A reversed bit string, misplaced measurement, parameter-binding mistake, transpiler transformation, or noisy backend can make correct code look broken. This guide provides a systematic Qiskit debugging workflow, a symptom-to-cause table, a reusable checklist, and a record-keeping template for isolating errors before changing the algorithm.
Overview
Quantum debugging is different from debugging an ordinary deterministic program. A circuit can be logically correct while its output changes because measurements are probabilistic, simulator settings differ, or hardware introduces noise. The first goal is therefore to separate a circuit error from an interpretation error and an execution-environment difference.
Use this order whenever a Qiskit result looks wrong:
- Write down the expected state, bit string, or probability distribution.
- Check qubit, classical-bit, and displayed-string ordering.
- Inspect where measurements occur and whether every required qubit is measured.
- Run a small ideal simulation with a fixed shot count and, where useful, a fixed random seed.
- Compare statevector or amplitude information with measured counts.
- Inspect the transpiled circuit rather than assuming it matches the source circuit.
- Verify parameter values and binding before execution.
- Only then investigate backend noise, calibration, queue-time differences, or mitigation methods.
This sequence keeps one variable changing at a time. It also makes failures easier to reproduce when moving between local simulation, a cloud simulator, and quantum hardware.
Checklist by scenario
The counts contain the opposite bit order
Qiskit commonly displays classical-register results with the highest-index classical bit on the left. As a result, a circuit that places a value in qubit 0 may display a string whose rightmost character represents that bit. For example, a measured state that you describe internally as qubit 0 = 1 and qubit 1 = 0 may appear as 01, depending on the classical-bit mapping.
- Draw the circuit and inspect the wires from top to bottom.
- Record the mapping from each qubit to each classical bit.
- Compare individual bit positions, not only the complete displayed string.
- Use an explicit conversion or relabeling step in analysis code instead of relying on visual memory.
- Check whether multiple classical registers are being printed with register separators.
Do not “fix” the circuit until you have confirmed that the result is genuinely wrong rather than reversed in presentation.
The result is always zero or has no counts
Start with measurement placement. A simulator or backend cannot return useful classical counts if the circuit has no measurements, if measurements occur before the gates you intended to observe, or if the measurement target is not connected to the expected classical bit.
- Confirm that measurements are at the end of the logical experiment, unless mid-circuit measurement is intentional.
- Check that the number of classical bits is sufficient.
- Verify that the measured qubits are the qubits changed by the circuit.
- Run a one-qubit test, such as applying an X gate and measuring the same qubit.
- Confirm that the execution result is being read from the correct circuit or job.
A tiny known-answer circuit is usually more informative than adding print statements to a large algorithm.
The statevector and counts appear to disagree
A statevector describes amplitudes before measurement; counts describe sampled measurement outcomes after measurement. They are related, but they are not the same output. A state with equal probabilities for two outcomes will not necessarily produce equal counts in a small run.
- Convert amplitudes to probabilities by taking the squared magnitude of each amplitude.
- Compare probabilities with normalized counts, not raw counts alone.
- Increase the shot count when checking an approximate distribution.
- Use an ideal, measurement-free circuit for statevector inspection when supported by the selected simulator.
- Remember that measuring a circuit changes the state being observed and may prevent later state inspection.
For a deterministic circuit, counts should concentrate on the expected result under ideal execution. For a probabilistic circuit, evaluate whether the observed distribution is plausible rather than expecting one exact string on every run.
The circuit works before transpilation but fails after transpilation
Transpilation rewrites a circuit to fit a target instruction set and coupling layout. It can change gate names, insert routing operations, alter depth, and introduce additional operations. The logical intent should be preserved, but hardware-oriented execution can expose assumptions that were hidden in the original circuit.
- Save or print the original circuit and the transpiled circuit side by side.
- Specify the intended target backend or basis constraints when comparing runs.
- Inspect the transpiled depth, operation count, and qubit layout.
- Check whether your analysis assumes a particular physical-qubit order.
- Test the transpiled circuit on an ideal simulator before submitting it to hardware.
If a circuit changes behavior on an ideal simulator after transpilation, investigate mapping, parameter handling, or measurement interpretation first. If it changes only on hardware, noise and calibration become stronger candidates.
Parameterized circuits produce an unexpected result
Parameter bugs can be subtle because the circuit may build and execute successfully. Confirm that every parameter has a value, that the binding targets the parameters used by the circuit, and that angle units match your expectation. A value intended as degrees but passed as radians can produce a valid yet surprising rotation.
- Print the parameter names and the final numeric values.
- Test one simple parameter value with a known outcome, such as zero or a half-turn.
- Check the order of values when using positional binding.
- Prefer named mappings when readability and safety matter.
- Verify that each generated circuit receives the intended binding rather than sharing mutable state accidentally.
| Symptom | Likely cause | First check |
|---|---|---|
| Expected 10, observed 01 | Bit-string or register-order interpretation | Classical-bit mapping and display convention |
| Only 0 outcomes appear | Missing measurement, wrong target, or untouched qubits | Measurement instructions and a one-qubit test |
| Counts vary between runs | Sampling randomness or backend noise | Shot count, seed, and ideal-versus-hardware comparison |
| Statevector looks correct but counts do not | Probability conversion or insufficient shots | Squared amplitudes and normalized counts |
| Local run works; hardware does not | Noise, routing overhead, or backend configuration | Transpiled depth and ideal simulator baseline |
| Parameterized results are inconsistent | Unbound, misordered, or incorrectly scaled parameters | Final bound values and angle units |
What to double-check before changing the algorithm
Separate randomness from failure
Shot-based execution samples a distribution. A different count on a second run is not automatically a bug. For reproducible development, use a fixed simulator seed where the selected simulator and current API support it, record the shot count, and compare distributions rather than individual samples. Seeds can help reproduce a debugging session, but they do not make hardware deterministic.
Inspect the complete execution path
Record the circuit construction, transpilation options, backend or simulator, number of shots, seed settings, parameter values, and result-processing code. A correct circuit can still produce a misleading report if the analysis reads the wrong classical register or labels outcomes with the wrong qubit order.
Use progressively larger tests
Begin with a single gate and one measured qubit. Then test a two-qubit gate, a small entangled circuit, the parameterized version, and finally the full algorithm. This progression identifies the first layer at which the expectation and observation diverge. It is usually faster than debugging a complete variational or oracle-based circuit in one pass.
A useful experiment record looks like this:
Expected:
Logical state or probability distribution: ...
Bit interpretation: q0 -> c0, q1 -> c1
Observed:
Counts or statevector summary: ...
Number of shots: ...
Execution:
Qiskit and simulator/backend versions: ...
Transpilation target and settings: ...
Parameters and units: ...
Seed settings: ...
Noise or hardware enabled: yes/no
First divergence:
Original circuit / transpiled circuit / measurement / analysis: ...
Common mistakes in quantum circuit troubleshooting
- Changing several gates at once: This removes the evidence needed to identify the original fault.
- Reading a count string as a qubit diagram: Display order and wire order may not match intuitive left-to-right reading.
- Comparing raw counts with amplitudes: Counts are samples; amplitudes require probability conversion.
- Ignoring transpilation: Hardware execution rarely uses exactly the source circuit.
- Assuming a seed controls hardware: A simulator seed may reproduce sampling behavior, not physical device noise.
- Testing only on a large circuit: Small known-answer tests provide a clearer failure boundary.
- Copying old examples without checking APIs: Qiskit interfaces, simulator options, and backend workflows can change across releases. Confirm the installed version and consult the matching documentation.
For a broader reproducibility practice, keep the circuit source, environment information, execution settings, and result interpretation together. The Quantum Experiment Reproducibility Checklist can help structure that record. If resource growth is the issue rather than an incorrect result, review the quantum circuit resource estimation guide before submitting another run.
When to revisit this workflow
Return to this checklist whenever a new circuit fails, a simulator and hardware result diverge, or code is ported between Qiskit versions. Recheck it after changing the transpilation target, adding parameters, moving from statevector analysis to shot-based measurement, or introducing noise and error-mitigation steps.
Because SDK interfaces and backend execution requirements can evolve, review the relevant Qiskit and provider documentation after major releases and refresh team examples periodically. Before your next run, complete these final actions:
- Write the expected output in logical qubit terms.
- Document the classical-bit mapping and measurement locations.
- Run a minimal ideal test and record its result.
- Inspect the transpiled circuit and parameter bindings.
- Compare normalized counts with the expected probability distribution.
- Only then attribute remaining differences to backend noise or algorithmic behavior.
This habit turns “wrong result” from a vague diagnosis into a sequence of testable questions—and makes quantum programming failures easier to reproduce, explain, and fix.