Quantum Computing Troubleshooting Guide

Diagnose first

Check the depth of the circuit after transpilation, not before. The raw circuit depth is meaningless; what runs on the chip is the transpiled version, which can be much deeper due to SWAP insertion.

from qiskit import transpile

# Check depth before and after transpilation
print("Original depth:", qc.depth())

transpiled = transpile(qc, backend=backend, optimization_level=1)
print("Transpiled depth (opt 1):", transpiled.depth())

transpiled_opt = transpile(qc, backend=backend, optimization_level=3)
print("Transpiled depth (opt 3):", transpiled_opt.depth())

Fixes

• Use optimization_level=3 in transpile(). This applies Sabre routing and gate cancellation. Depth reductions of 30-60% are common.
• Rewrite multi-qubit gates using only native gates (cx, u, ecr depending on backend). Each non-native gate decomposes into several native gates, multiplying depth.
• Replace CCX (Toffoli) gates with the 6-CNOT relative-phase variant where phase accuracy is not required.
• Split long circuits into subcircuits and use mid-circuit measurement or classical feed-forward where the algorithm allows.

Diagnose

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService()
backend = service.backend("ibm_sherbrooke")

# Print the coupling map to see which qubit pairs can interact directly
print(backend.coupling_map)

Fix: specify an initial layout that respects connectivity

from qiskit import transpile

# Place your logical qubits on physically connected hardware qubits
# Check the coupling map first: [0, 1] and [1, 2] are connected on most IBM devices
transpiled = transpile(
    qc,
    backend=backend,
    initial_layout=[0, 1, 2],   # maps qc qubit 0 -> hw qubit 0, etc.
    optimization_level=3,
)
print("SWAP count:", transpiled.count_ops().get('swap', 0))

Alternative: let Sabre routing pick the layout

With optimization_level=3 and no initial_layout, Qiskit's Sabre layout pass tries multiple random seeds and picks the lowest-SWAP result. This is often better than a manual layout unless you have specific knowledge of qubit quality.

Fix: add measurements after all gates

from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)

# Measurements must come AFTER all gates
qc.measure([0, 1], [0, 1])
# OR: qc.measure_all(), adds measurements to all qubits

sim = AerSimulator()
job = sim.run(qc, shots=1024)
print(job.result().get_counts())

Check barrier placement

A qc.barrier() is only a visual/scheduling hint; it does not cause measurements to run early. But if you used measure_all() and then added more gates, those gates run after measurement on the classical register and have no effect on measured outcomes. Always draw the circuit to confirm order: print(qc.draw()).

Fixes

• For simulation: AerSimulator handles 30+ qubits with the statevector method, and significantly more with the matrix product state method (see Problem 10).
• For hardware: choose a backend with enough qubits, or reduce your algorithm's qubit count by reusing qubits (reset and reuse mid-circuit with qc.reset()).

from qiskit_aer import AerSimulator

# Statevector handles ~30 qubits; MPS handles wider circuits
sim = AerSimulator(method='statevector')  # up to ~30 qubits
sim_mps = AerSimulator(method='matrix_product_state')  # handles more

# Check a backend's qubit count before submitting
from qiskit_ibm_runtime import QiskitRuntimeService
service = QiskitRuntimeService()
for b in service.backends():
    print(b.name, b.num_qubits)

Fix: transpile with explicit basis_gates

from qiskit import transpile, QuantumCircuit

qc = QuantumCircuit(3)
qc.ccx(0, 1, 2)   # Toffoli: not native on most superconducting hardware

# transpile() decomposes CCX into cx + u gates automatically
transpiled = transpile(
    qc,
    basis_gates=['cx', 'u'],
    optimization_level=2,
)
print(transpiled.draw())
print("Gate counts:", transpiled.count_ops())

To see what gates a specific backend supports natively:

print(backend.basis_gates)
# e.g. ['cx', 'id', 'rz', 'sx', 'x']

Diagnose: run on a noiseless simulator first

from qiskit_aer import AerSimulator

# Step 1: confirm the algorithm works without noise
sim = AerSimulator(method='statevector')
job = sim.run(qc, shots=4096)
counts = job.result().get_counts()
print("Noiseless result:", counts)

# Step 2: add a noise model from real hardware to test noise impact
from qiskit_aer.noise import NoiseModel
from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService()
backend = service.backend("ibm_nairobi")
noise_model = NoiseModel.from_backend(backend)

noisy_sim = AerSimulator(noise_model=noise_model)
noisy_job = noisy_sim.run(qc, shots=4096)
print("Noisy result:", noisy_job.result().get_counts())

Fixes

• If the noiseless simulator is correct and hardware is not: reduce circuit depth, apply error mitigation (see Qiskit's ZNE or M3 packages), or use a higher-fidelity backend.
• If both are wrong: the algorithm has a design flaw. Verify with a small test case on the statevector simulator.
• Increase shots to at least 4096 before concluding results are random. Low shot counts produce high variance on even correct circuits.

Diagnose: plot cost vs iteration

import numpy as np
import matplotlib.pyplot as plt
from qiskit.primitives import StatevectorEstimator
from qiskit_algorithms import VQE
from qiskit_algorithms.optimizers import SPSA

costs = []

def callback(nfev, params, energy, stddev):
    costs.append(energy)

vqe = VQE(
    estimator=StatevectorEstimator(),
    ansatz=ansatz,
    optimizer=SPSA(maxiter=200),
    callback=callback,
    initial_point=np.random.uniform(-np.pi, np.pi, ansatz.num_parameters),
)
result = vqe.compute_minimum_eigenvalue(hamiltonian)

plt.plot(costs)
plt.xlabel("Iteration")
plt.ylabel("Energy")
plt.title("VQE convergence")
plt.show()

Fixes

• Barren plateaus: reduce circuit depth, switch to local cost functions, use layerwise training (freeze earlier layers while training new ones).
• Bad ansatz: for chemistry problems, use UCCSD (Unitary Coupled Cluster Singles and Doubles) rather than a hardware-efficient ansatz. The expressibility needs to match the problem.
• Hardware optimizers: use SPSA instead of gradient descent on real hardware. SPSA estimates gradients with only two circuit evaluations regardless of parameter count, and tolerates shot noise better than finite-difference methods.
• Initial parameters: try the INTERP strategy: solve a simpler version of the problem first (e.g. fewer QAOA layers) and use those optimal parameters as the starting point for the harder version.

Fix: verify the Pauli decomposition

import numpy as np
from qiskit.quantum_info import SparsePauliOp

# If you built the Hamiltonian manually, verify it matches the matrix form
H_matrix = np.array([[-1, 0], [0, 1]], dtype=complex)

H_pauli = SparsePauliOp.from_operator(H_matrix)
print("Pauli decomposition:", H_pauli)
# Should give: -1.0 * I + 1.0 * Z  ->  SparsePauliOp(['I', 'Z'], coeffs=[-1.+0.j,  1.+0.j])

# Check that reconstructing the matrix matches the original
H_reconstructed = H_pauli.to_matrix()
print("Max error:", np.max(np.abs(H_matrix - H_reconstructed)))

Also check the sign convention for the Hamiltonian in the algorithm. VQE minimises energy, so it expects H to be defined such that the ground state has the lowest eigenvalue. If your H has the wrong sign, VQE will converge to the wrong state.

Practical advice: use 1024 shots for prototyping. Use 8192 for results you plan to report. When shot noise is not what you are studying, use AerSimulator(method='statevector') with no shot limit; it gives exact probabilities and runs faster than 1,000,000 shots on large circuits.

Fix: use the right simulator method for your circuit

from qiskit_aer import AerSimulator

# Default statevector: exact, but limited to ~30 qubits
sim_sv = AerSimulator(method='statevector')

# Matrix product state: efficient for low-entanglement circuits
# Handles 100+ qubits when entanglement is local
sim_mps = AerSimulator(method='matrix_product_state')

# Stabilizer: exponentially fast for Clifford-only circuits (H, S, CNOT, measure)
sim_clifford = AerSimulator(method='stabilizer')

# GPU-accelerated statevector: requires aer-gpu package and CUDA GPU
# pip install qiskit-aer-gpu
sim_gpu = AerSimulator(method='statevector', device='GPU')

Which method to choose

• MPS: best for circuits where qubits interact only with nearby qubits (e.g. 1D variational circuits, QAOA on ring graphs). Accuracy degrades for highly entangled states.
• Stabilizer: only works for Clifford circuits (no T gates, no arbitrary rotations), but is exact and runs in polynomial time.
• GPU: best if you have a CUDA GPU and need statevector accuracy on 25-32 qubits. A GPU with 16 GB VRAM handles about 30 qubits.

Fixes

• Switch to method='matrix_product_state' if your circuit has limited entanglement (see Problem 10).
• Use AWS Braket SV1 (supports up to 34 qubits) or the local MPS simulator for wider circuits.
• Restructure the algorithm to use fewer qubits. Many algorithms can be run in segments, reusing qubits via mid-circuit reset: qc.reset(qubit).

Fix: assign parameters before serialising, or use OpenQASM

from qiskit import QuantumCircuit
from qiskit.circuit import ParameterVector
from qiskit import qasm3
import json

# Parameterised circuit
params = ParameterVector('theta', 3)
qc = QuantumCircuit(3)
qc.ry(params[0], 0)
qc.ry(params[1], 1)
qc.ry(params[2], 2)

# Option 1: assign parameters before pickling
bound_qc = qc.assign_parameters({params[0]: 1.2, params[1]: 0.5, params[2]: 0.9})
import pickle
data = pickle.dumps(bound_qc)   # now safe to serialise

# Option 2: serialise as OpenQASM 3 (text format, always portable)
qasm_str = qasm3.dumps(qc)
with open('circuit.qasm', 'w') as f:
    f.write(qasm_str)

# Load it back
qc_loaded = qasm3.loads(qasm_str)

Fix: find the least-busy backend

from qiskit_ibm_runtime import QiskitRuntimeService

service = QiskitRuntimeService()

# Get all operational backends and sort by pending jobs
backends = service.backends(operational=True, simulator=False)
ranked = sorted(backends, key=lambda b: b.status().pending_jobs)

for b in ranked[:5]:
    status = b.status()
    print(f"{b.name}: {status.pending_jobs} pending jobs, {b.num_qubits} qubits")

Other strategies

• Run on the local AerSimulator while your hardware job queues. For most debugging purposes the simulator result is sufficient.
• Submit jobs during off-peak hours (late night UTC) when queues are shorter.
• Use a different IBM Quantum region if available on your plan (US, EU, AP regions have separate queues).

Fixes

• Reduce circuit depth with optimization_level=3 during transpilation (see Problem 1).
• Split a batch of circuits into smaller submission chunks.
• Check the gate count before submitting: transpiled.count_ops() shows gate counts by type.

from qiskit import transpile

transpiled = transpile(qc, backend=backend, optimization_level=3)

# Inspect total gate count
ops = transpiled.count_ops()
total_gates = sum(ops.values())
print(f"Total gates: {total_gates}")
print(f"Two-qubit gates: {ops.get('cx', 0) + ops.get('ecr', 0)}")

# Check circuit depth
print(f"Circuit depth: {transpiled.depth()}")

Fix: use provider-recommended transpilation

• Quantinuum: use pytket-quantinuum which applies Quantinuum-specific optimisation passes and compiles to native ZZMax gates.
• IonQ: use the Amazon Braket SDK or Azure Quantum SDK which handle IonQ transpilation to GPi, GPi2, and MS (Molmer-Sorensen) gates natively.
• Check published two-qubit gate fidelity for the specific system you are targeting before assuming results are wrong. Quantinuum H2 achieves ~99.9% but IonQ's Aria is closer to 97-99% for typical circuits.

Diagnose: check gradient variance across random initialisations

import pennylane as qml
import numpy as np

dev = qml.device("default.qubit", wires=6)

@qml.qnode(dev)
def circuit(params):
    for i in range(6):
        qml.RY(params[i], wires=i)
    for i in range(5):
        qml.CNOT(wires=[i, i + 1])
    for i in range(6):
        qml.RY(params[i + 6], wires=i)
    return qml.expval(qml.PauliZ(0))

# Measure gradient variance over many random parameter sets
grad_fn = qml.grad(circuit)
variances = []
for _ in range(100):
    params = np.random.uniform(0, 2 * np.pi, 12)
    grad = grad_fn(params)
    variances.append(np.var(grad))

print(f"Mean gradient variance: {np.mean(variances):.2e}")
# If this is below 1e-4, you likely have a barren plateau

Fixes

• Layerwise training: train one layer at a time, freezing previously trained layers. This avoids initialising all parameters randomly at the same time.
• Local cost functions: instead of measuring a global observable (sum over all qubits), use a local observable (single qubit) which has gradients that vanish only polynomially, not exponentially.
• Reduce depth: barren plateaus worsen with circuit depth. Fewer layers with higher expressibility per layer is better than many shallow layers.
• Identity initialisation: initialise parameters so the circuit is close to the identity at the start. Gradients are larger near the identity.

See also: PennyLane noise mitigation tutorial for related techniques.

Fix: use qml.numpy or a framework tensor consistently

import pennylane as qml
import pennylane.numpy as pnp   # use this, not plain numpy
import numpy as np

dev = qml.device("default.qubit", wires=2)

@qml.qnode(dev, interface="autograd")
def circuit(params):
    qml.RY(params[0], wires=0)
    qml.RY(params[1], wires=1)
    qml.CNOT(wires=[0, 1])
    return qml.expval(qml.PauliZ(0))

# WRONG: plain numpy array, gradients will not work
# params = np.array([0.5, 1.2])

# CORRECT: use pnp (pennylane numpy) and mark as requiring grad
params = pnp.array([0.5, 1.2], requires_grad=True)

grad_fn = qml.grad(circuit)
print("Gradient:", grad_fn(params))

For PyTorch or JAX users

import torch

@qml.qnode(dev, interface="torch")
def circuit_torch(params):
    qml.RY(params[0], wires=0)
    qml.RY(params[1], wires=1)
    return qml.expval(qml.PauliZ(0))

# Use torch tensors throughout; do NOT mix with numpy in the same graph
params_torch = torch.tensor([0.5, 1.2], requires_grad=True)
result = circuit_torch(params_torch)
result.backward()
print("Gradient:", params_torch.grad)