Tessera: Quantum Circuit Transpiler

FAQ & Troubleshooting

Common questions and every error Tessera can raise, with causes and fixes.

Errors

ValueError: Backend chosen does not exist in current BACKEND_REGISTRY

You passed a backend name that Tessera doesn't recognise.

transpile(qc, backend="GOOGLE")  # not a registered backend

Fix: use one of the supported backend keys: "IBM", "IONQ", or "RIGETTI". See the Backends page for the full list.

ValueError: Coupling map key '...' not found in COUPLING_MAP_REGISTRY

You passed a string coupling map key that doesn't exist in the registry.

Fix: use one of the supported keys ("IBM_DEFAULT", "IBM_BRISBANE", "IBM_SHERBROOKE", "IONQ_ARIA", "IONQ_FORTE", "RIGETTI_ANKAA", "RIGETTI_ANKAA_9Q"), or pass a TesseraCouplingMap instance directly. See the Coupling Maps page.

ValueError: Circuit with N qubits is too big for coupling map with M qubits

Your circuit has more qubits than the target coupling map supports.

Fix: either reduce the circuit qubit count, choose a larger coupling map (e.g. "IBM_BRISBANE" for 127 qubits), or provide a custom TesseraCouplingMap with enough qubits.

ValueError: No decomposition found for gate '...' in ... backend

Your circuit contains a gate that has no decomposition defined for the target backend. This can happen if:

  • You are using a gate that Tessera supports on some backends but not the one you chose
  • You are using a custom gate that Tessera doesn't know about at all

Fix: check the Gate Reference page to confirm the gate is supported on your backend. If you are adding a new backend and hit this error, your decomposition map is missing an entry for this gate.

ValueError: Unknown gate '...'. Add it to the GATE_MAP in gate_library.py if needed

Tessera tried to convert a gate back to Qiskit format but the gate name isn't in the gate library. This most commonly happens when a custom pass introduces a gate name that has no Qiskit equivalent registered.

Fix: add the gate to GATE_MAP in tessera/gate_library.py following the existing pattern.

ValueError: No layout found on circuit. Run a layout pass before BasicSwapRouter

BasicSwapRouter ran on a circuit with no layout. This should not happen when using the standard transpile() API since DenseLayoutPass always runs before routing. If you are building a custom pipeline using TesseraPassManager directly, make sure a layout pass runs before BasicSwapRouter.

ValueError: BasicSwapRouter encountered a N-qubit gate '...'. Decompose to 2-qubit gates first

The router encountered a gate acting on more than 2 qubits. BasicSwapRouter only handles single and two-qubit gates.

Fix: ensure BasisTranslationPass runs before BasicSwapRouter in your pipeline. All three-qubit gates (e.g. ccx) must be decomposed before routing.

ValueError: No path exists between qA and qB in the coupling map

The router could not find a path between two physical qubits. This means the coupling map is disconnected, which means there is no sequence of connected qubits linking the two positions.

Fix: verify your coupling map is fully connected. All built-in coupling maps are fully connected. If you are using a custom coupling map, check that every qubit can reach every other qubit through the graph.

Common Questions