QChecker: Static Bug Detection for Qiskit
- QChecker is a pattern-based static analyzer for Qiskit programs, detecting quantum-specific bugs through tailored AST extraction and pre-defined bug patterns.
- It uses a two-stage architecture that first extracts quantum program structures and then applies eight bug detectors to identify issues like gate misuse and register mismatches.
- Empirical evaluation on Bugs4Q shows high recall and efficiency, though its pattern-based approach may miss output errors and is largely Qiskit-centric.
Searching arXiv for recent and directly relevant papers on “QChecker” and closely related names to ground the article. QChecker is a static analysis tool that supports finding bugs in quantum programs in Qiskit. Rather than executing a quantum program on a simulator or quantum hardware, it analyzes source code, extracts quantum-program-specific structure from the abstract syntax tree (AST), and matches that extracted information against bug patterns distilled from previously studied real bugs in quantum software. The tool is presented as the first static analysis tool dedicated to finding these kinds of bugs in Qiskit, and it was evaluated on the Bugs4Q benchmark (Zhao et al., 2023).
1. Naming and scope
The exact name QChecker refers most directly to the Qiskit-oriented static analyzer for quantum programs just described. Closely named systems on arXiv serve different purposes and should be distinguished from it. The open-source qChecker package in computing education is designed to find statement-level anti-patterns in syntax trees and provide feedback to programming novices (Naude et al., 2024). CodeChecker is an open source static analysis infrastructure built around the LLVM/Clang Static Analyzer tool-chain for C++ development workflows (Horvath et al., 2024). QuCheck is a property-based testing framework for quantum programs in Qiskit, and QuickCheck for VDM is a lightweight verification tool for categorising proof obligations (Pontolillo et al., 28 Mar 2025); (Battle et al., 2024).
| Name | Role | arXiv id |
|---|---|---|
| QChecker | Static bug detector for Qiskit programs | (Zhao et al., 2023) |
| qChecker | Python anti-pattern detector for novice code | (Naude et al., 2024) |
| CodeChecker | Static analysis infrastructure for C/C++ | (Horvath et al., 2024) |
| QuCheck | Property-based testing framework in Qiskit | (Pontolillo et al., 28 Mar 2025) |
| QuickCheck for VDM | Proof-obligation triage tool for VDM | (Battle et al., 2024) |
This naming proximity is consequential because the tools differ not only by application domain, but also by checking paradigm. QChecker is a pattern-based static analyzer for source code. By contrast, QuCheck is a dynamic property-based testing framework, and the educational qChecker is an AST/syntax-tree-based anti-pattern detector for novice Python code. The shared “checker” suffix therefore does not imply a shared analysis model.
2. Problem setting and motivation
QChecker is motivated by the observation that many existing debugging and testing techniques for quantum programs are dynamic: they run the program, often repeatedly, on simulators or cloud-accessed backends. The paper argues that static analysis is attractive in quantum software for the same reasons it is attractive in classical software—speed and low cost—but also that existing classical static analyzers are unsuitable for analyzing quantum programs (Zhao et al., 2023).
The paper identifies several reasons for that unsuitability. Traditional Python analyzers can find ordinary syntax or API misuse, but they do not understand qubits, quantum/classical registers, measurement collapse, basis gates, backend limitations, or the fact that quantum logic is expressed as circuit-building operations rather than ordinary imperative state updates. In Qiskit, program meaning is spread across register declarations, circuit construction, gate calls, measurements, backend selection, and execution calls. A checker therefore has to reason about all of that structure together.
The authors also emphasize quantum-specific constraints that motivate dedicated static checking. Measured qubits should not later be reused in entangling control roles; register sizes must match circuit usage; gates must be valid for the selected backend; and backend or QASM-related APIs impose framework-specific restrictions. QChecker is positioned as a tool for finding such defects without executing the target program.
3. Architecture and program representation
QChecker has a two-stage architecture: AST-based information extraction and bug-pattern-based detection (Zhao et al., 2023). A source quantum program is first parsed into an AST. The extraction logic is implemented in the module Ast_Operator. The extracted information is then stored into two internal data structures, QP_Attribute and QP_Operation, which are subsequently passed to a collection of bug detectors. The output is a report containing the buggy program location, line number, bug type, and textual description.
QP_Attribute records variable-level information. For each variable, QChecker stores the variable name, variable value, variable type, and source-code location or line. Variable values may come from a constant, another variable, or the result of a function calculation. The paper’s examples show that QP_Attribute is used not only for ordinary Python assignments but also for Qiskit-relevant objects such as backends, quantum registers, classical registers, circuits, jobs, and result objects.
QP_Operation stores function-call-level information. For each call, QChecker stores the function call itself, a list of arguments, type and value of each argument, position or location, and related call metadata. The paper describes QP_Operation as a list containing all function calls in the program file, together with a richer internal table indexing metadata by function-call strings. The example operations include backend acquisition, register construction, circuit construction, gate applications, measurement calls, execution calls, and result retrieval.
The extraction stage supports “complex syntax and data structures such as dictionaries, lists, function definitions, loops, and conditional branches.” This support is important because Qiskit programs often intertwine ordinary Python constructs with quantum-specific APIs. The paper also states that this design helps QChecker trace relationships between variables and function calls, including cases where a variable is modified multiple times, where a variable name changes when passed as a function argument, and where the initial value of a variable needs to be traced back.
Programs with basic syntax errors are not analyzed. The paper explicitly lists Python indentation errors, unrecognized operators, undefined variables, and undefined functions as examples. Such files are reported as syntax errors and excluded from static checking.
4. Detector taxonomy and bug patterns
QChecker’s second stage consists of eight detectors derived from bug patterns reported in prior empirical studies on quantum bugs, especially Bugs4Q and a prior bug-pattern study by the same authors (Zhao et al., 2023).
| Detector | Expansion | Covered patterns |
|---|---|---|
| IG | Incorrect uses of quantum gates | Gates not among basis gates; custom multi-qubit gates; random gate not defined |
| MI | Measurement related issue | Post-measurement misuse of qubits in later double-qubit gates |
| IS | Incorrect initial state | Insufficient qubits; qubit count larger than registers defined; insufficient classical-register length |
| PE | Parameter error | Incorrect gate parameters; classical bits used for entanglement; duplicate physical qubits; malformed coupling_map |
| CM | Command misuse | Unrecognized parameters; wrong command used; redundant classical registers; circuit interaction error |
| CE | Call error | Object call error; import error; backend error; translating error |
| QE | QASM error | Problems with qasm_simulator or QASM program construction |
| DO | Discarded orders / deprecated methods | Deprecated API use |
The IG detector checks whether quantum gates are used correctly. It inspects gate calls and checks whether the gate is recognized by Qiskit, whether it has been defined, whether custom gates conform to specifications, and whether three-qubit gates comply with required conventions. The MI detector targets measurement-related misuse. After a measure call, QChecker iterates through subsequent operations and determines whether the measured qubit appears as a control qubit in double-qubit gate operations. The paper illustrates this with a teleportation-style example in which qubits are measured and then reused as controls in later cx and cz operations.
The IS detector checks whether the initialized register state is sufficient and valid for the whole program, rather than only verifying that register declarations are syntactically legal. The paper states that Aer.get_backend('qasm_simulator') supports fewer than 30 qubits for measurement operations and BasicAer.get_backend('qasm_simulator') supports fewer than 24 qubits, based on the authors’ validation. The detector uses backend choice, register declarations, qubit indices referenced in operations, and measurement targets against classical-register lengths.
The PE detector inspects parameter count and types, checks whether parameters expected to be qubits are actually quantum references rather than classical-register values, checks numerical parameter types, inspects multi-qubit operations for nonexistent parameter positions, inspects qubit-to-physical-qubit assignment structures for duplicate occupancy, and checks whether coupling_map receives a list. The paper’s example uses a layout dictionary in which both qreg[0] and qreg[5] are mapped to physical qubit 12. The CM detector checks for wrong or improper use of commands, including unrecognized parameters and wrong command use. Its example involves pulse.shiftphase(...), which the paper states is unrecognized in the relevant module context.
The CE detector addresses call-related errors involving package calls, backend simulator calls, translator calls, and some parameter declaration problems. The paper gives a ProcessTomography(...) example and notes that this kind of bug is hard to detect; the detector can only judge one scenario now. The QE detector is described at a higher level as checking problems with qasm_simulator or when building QASM programs. The DO detector checks whether a called method is deprecated because of version updates.
The detector set is explicitly pragmatic rather than semantic-complete. The paper does not define a semantic proof system, abstract domain lattice, transfer functions, or intermediate control-flow graph formalism. It presents QChecker as a pattern-based static analyzer whose novelty lies in AST extraction tailored to Qiskit semantics and in detector rules grounded in observed defect classes.
5. Empirical evaluation
QChecker was evaluated on Bugs4Q, described in the paper as a realistic benchmark of 42 real-world buggy quantum programs in Qiskit (Zhao et al., 2023). For each bug in Bugs4Q, the benchmark’s bug type is treated as ground truth; if QChecker’s reported bug type matches that type, the case is counted as a True Positive (TP), otherwise as a False Positive (FP), while benchmark bugs not detected by QChecker are False Negatives (FN). The paper reports the standard metrics:
Across the 42 buggy Qiskit programs, QChecker found 24 bugs. The overall performance table reports Precision: 0.625, Recall: 0.882, F1-score: 0.731, and Average time per program: 48.2 ms. The detector-wise distribution reported in the paper is that PE found 10 bugs, CE found 7 bugs, IS found 2 bugs, and each other detector found 1 bug.
Runtime efficiency is a central empirical claim. The experiments were run on an Intel i9-10940X CPU, 128 GB RAM, Ubuntu 20.04, and Python 3.10. The paper contrasts QChecker’s 48.2 ms per program average detection time with dynamic execution costs. It reports an average actual execution time of 2.14 seconds for the 42 Bugs4Q programs, with average program size 31 LOC. This is used to argue that static analysis can provide a substantially cheaper first pass than program execution.
The evaluation also establishes clear boundaries. Of the 42 bugs in Bugs4Q, 22 are output errors, meaning that the output does not match user expectations. The authors state that QChecker cannot detect these because they require reasoning about intended behavior or actual produced outputs, not just static patterns. The study also does not compare QChecker against PyLint, generic Python static analyzers, dynamic quantum debuggers, or other static quantum analyzers; it is therefore a single-tool feasibility and effectiveness study rather than a head-to-head benchmarking exercise.
6. Limitations and place in the literature
The paper is explicit that QChecker detects only bugs represented by its manually distilled pattern set (Zhao et al., 2023). This makes the tool inherently incomplete: if a bug does not match one of the encoded patterns, the tool will miss it. The most practically important limitation is the inability to detect many output errors; the paper singles out the 22 output-mismatch bugs in Bugs4Q as beyond QChecker’s scope. Programs with basic syntax errors are excluded before analysis, so QChecker is not a general parser-recovery or syntax-debugging tool.
QChecker is also strongly Qiskit-centric. The paper reports that the extraction phase can build QP_Attribute- and QP_Operation-style outputs for a small Cirq example, suggesting some reuse of the AST extraction machinery across Python-based quantum languages. At the same time, the detector rules are Qiskit-specific, and the paper shows a concrete extraction failure on ProjectQ because quantum operations there use an overloaded | operator. The result is a checker whose portability is limited by both framework syntax and API semantics.
The tool is therefore best understood as a fast, lightweight pre-execution checker for Qiskit code, especially for API misuse, register sizing problems, backend or gate incompatibilities, measurement misuse, and certain parameter or configuration errors. It is not a correctness prover and not a replacement for testing. This positioning is reinforced by adjacent work in quantum software engineering. QuCheck later approached Qiskit from the complementary direction of property-based testing, reporting that among the most thorough test configurations, those evaluating three properties achieved a mean mutation score ranging from 0.90 to 0.92 across five algorithms, with the false positive rate between 0 and 0.04 (Pontolillo et al., 28 Mar 2025). QChecker and QuCheck therefore occupy different points in the analysis space: one performs static pattern matching over source code, and the other performs statistical checking of semantic properties by executing generated tests.
In that broader context, QChecker’s significance lies in showing that quantum-program-specific static analysis is feasible, efficient, and capable of detecting a meaningful subset of real Qiskit defects. Its limitations—restricted pattern coverage, inability to detect output errors, and framework-specific extraction assumptions—are not peripheral details but part of the current definition of the tool.
