This document provides a comprehensive list of error codes generated by the Quantica compiler and runtime environment.
Errors occurring during the tokenization of the source code.
| Code | Description | Hints & Suggestions |
|---|---|---|
| E001 | Unterminated string literal | Hint: Make sure all string literals are properly closed with matching quotes Fix: Add a closing quote: "your string" |
| E002 | Unterminated character literal | Hint: Character literals must be enclosed in single quotes. Fix: Ensure the character ends with '. |
| E003 | Unterminated comment | Hint: Multi-line comments must be closed with */ |
| E004 | Invalid or unexpected character | Hint: The scanner encountered a character not allowed in the language. Fix: Remove the character or check for encoding issues. |
| E005 | Invalid escape sequence | Hint: Supported escapes usually include \n, \t, \r, \\, \".Fix: Fix the backslash sequence. |
| E006 | Invalid number literal | Hint: The number format is malformed (e.g., multiple decimal points). Fix: Correct the numeric syntax. |
| E007 | Invalid unicode escape | Hint: Unicode escapes usually look like \u{...}.Fix: Ensure valid hex digits inside the braces. |
| E008 | Unexpected end of input | Hint: The file ended abruptly while scanning a token. Fix: complete the code structure. |
| E009 | Invalid quantum notation | Hint: Quantum ket \|psi> or bra <phi\| syntax is incorrect.Fix: Verify \| and > or < placement. |
| E010 | Indentation error | Hint: Check that all lines in a block have consistent indentation |
Errors related to the structure and grammar of the code.
| Code | Description | Hints & Suggestions |
|---|---|---|
| E100 | Unexpected token | Hint: The parser found a token that doesn’t belong here. Fix: Check the previous line for missing delimiters. |
| E101 | Expected token not found | Hint: Check for missing colons after declarations. Fix: Add the required colon : after the declaration |
| E102 | Missing semicolon | Hint: Statements typically end with ;.Fix: Add ; at the end of the line. |
| E103 | Missing colon | Hint: Block definitions or type annotations require :.Fix: Add the missing colon. |
| E104 | Unmatched parenthesis | Hint: Check that all opening ( have matching )Fix: Add the missing ) or remove the extra ) |
| E105 | Unmatched bracket | Hint: An opening [ is missing its closing ].Fix: Balance the brackets. |
| E106 | Unmatched brace | Hint: An opening { is missing its closing }.Fix: Balance the curly braces. |
| E107 | Unexpected end of file | Hint: You may have an unclosed block or incomplete expression. Fix: Close all open blocks/functions. |
| E108 | Invalid expression syntax | Hint: The equation or expression is malformed. Fix: Check operator precedence and operands. |
| E109 | Invalid statement syntax | Hint: This line does not form a valid statement. Fix: Check keywords and structure. |
| E110 | Invalid function declaration | Hint: fn keyword usage or signature is wrong.Fix: Use fn name(params) -> Type { ... }. |
| E111 | Invalid class declaration | Hint: Class definition syntax is incorrect. Fix: Check class Name { ... } structure. |
| E112 | Invalid circuit declaration | Hint: circuit keyword usage is wrong.Fix: Define circuits using circuit Name(qubits) { ... }. |
| E113 | Invalid parameter list | Hint: Function parameters are malformed. Fix: Ensure format name: Type separated by commas. |
| E114 | Invalid argument list | Hint: Function call arguments are malformed. Fix: Separate arguments with commas. |
| E115 | Invalid block structure | Hint: Code block nesting is invalid. Fix: Check braces {} and indentation. |
| E116 | Invalid quantum declaration | Hint: Qubit or register declaration is wrong. Fix: Use qubit q or qreg q[n]. |
| E117 | Invalid gate expression | Hint: Gate application syntax is wrong. Fix: Use Gate @ qubit or Gate(params) @ qubit. |
| E118 | Invalid apply statement | Hint: The apply keyword is used incorrectly.Fix: Ensure target is a valid quantum object. |
| E119 | Malformed control flow | Hint: if, while, or for loop syntax is broken.Fix: Verify condition parentheses and block braces. |
| E120 | Invalid assignment target | Hint: You are trying to assign to something that isn’t a variable. Fix: Ensure the left side is a valid mutable variable. |
Errors occurring during static analysis and type validation.
| Code | Description | Hints & Suggestions |
|---|---|---|
| E200 | Type mismatch | Fix: Use type conversion functions: to_int(), to_float(). |
| E201 | Undefined variable | Hint: Make sure the variable is declared before use. Fix: Declare the variable first: let variable_name = value |
| E202 | Undefined function | Hint: Function name is misspelled or not imported. Fix: Check spelling or add import. |
| E203 | Undefined class | Hint: Class name is misspelled or not defined. Fix: Check spelling or definition. |
| E204 | Undefined member | Hint: Accessing a property that doesn’t exist on the object. Fix: Check class definition for the field. |
| E205 | Wrong number of arguments | Hint: Check the function signature. Fix: Adjust the number of arguments to match. |
| E206 | Incompatible types for operator | Hint: Operator (e.g., +, -) cannot be used with these types.Fix: Cast types or implement operator overloading. |
| E207 | Cannot assign to immutable variable | Hint: Variables declared with let are immutable.Fix: Change let to mut: mut variable_name = value |
| E208 | Return type mismatch | Hint: Function returns a type different from its signature. Fix: Update return statement or function signature. |
| E209 | Array element type mismatch | Hint: All array elements must usually be the same type. Fix: Ensure consistency in array literal. |
| E210 | Invalid array index type | Hint: Array indices must be integers. Fix: Cast the index to int or usize. |
| E211 | Invalid quantum register size | Hint: Size must be a constant positive integer. Fix: Use a valid integer literal for size. |
| E212 | Quantum type mismatch | Hint: Mixing classical and quantum types incorrectly. Fix: Use measure to convert quantum to classical. |
| E213 | Cannot call non-function type | Hint: Trying to use () on a variable that isn’t a function.Fix: Remove parentheses or check variable type. |
| E214 | Method not found on type | Hint: The method is not defined for this object. Fix: Check documentation for available methods. |
| E215 | Field not found on type | Hint: The field/property is not defined. Fix: Check the struct/class definition. |
| E216 | Invalid member access | Hint: Dot notation used on a primitive type. Fix: Only use . on objects/structs. |
| E217 | Annotation mismatch | Hint: let x: Int = "string" mismatch.Fix: Make the value match the type annotation. |
| E218 | Cannot infer type | Hint: Compiler needs help knowing the type. Fix: Add an explicit type annotation: : Type. |
| E219 | Circular type dependency | Hint: Type A includes Type B which includes Type A. Fix: Use references or pointers to break the cycle. |
| E220 | Invalid type for operation | Hint: This specific operation doesn’t support this type. Fix: Check documentation for supported types. |
Errors that occur while the program is executing.
| Code | Description | Hints & Suggestions |
|---|---|---|
| E300 | Null pointer dereference | Hint: Attempted to use a null or None value.Fix: Check for null before usage. |
| E301 | Division by zero | Hint: Add a check for zero before division. Fix: if denominator != 0: ... |
| E302 | Array index out of bounds | Hint: Index is larger than array length. Fix: Check array bounds: if index < len(array) |
| E303 | Stack overflow | Hint: Infinite recursion detected. Fix: Check recursive base cases. |
| E304 | Out of memory | Hint: Program allocated too much RAM. Fix: Optimize data structures or fix leaks. |
| E305 | Assertion failed | Hint: assert(condition) returned false.Fix: Review the assertion logic. |
| E306 | Invalid type cast | Hint: Runtime casting failed. Fix: Check type compatibility before casting. |
| E307 | Uninitialized variable | Hint: Reading a variable before writing to it. Fix: Initialize variable at declaration. |
| E308 | Invalid operation | Hint: Operation illegal in current state. Fix: Check program flow. |
| E309 | Resource not available | Hint: File, socket, or device is busy/missing. Fix: Handle I/O errors gracefully. |
| E310 | Operation timeout | Hint: Process took too long. Fix: Optimize code or increase timeout limits. |
| E311 | Invalid program state | Hint: Logic error reached undefined state. Fix: Debug state machine logic. |
| E312 | Quantum measurement error | Hint: Measurement failed (hardware or sim issue). Fix: Retry or check noise models. |
| E313 | Gate application error | Hint: Gate failed to apply. Fix: Check qubit availability. |
| E314 | Register size mismatch | Hint: Operations require matching register sizes. Fix: Resize registers to match. |
| E315 | Qubit index out of bounds | Hint: Accessing qubit q[5] in a 3-qubit system.Fix: Check register dimensions. |
Logical errors in valid syntax.
| Code | Description | Hints & Suggestions |
|---|---|---|
| E400 | Duplicate declaration | Hint: Name already defined in this scope. Fix: Rename the variable/function. |
| E401 | Invalid scope access | Hint: Variable is private or out of scope. Fix: Check visibility modifiers ( pub). |
| E402 | Break outside loop | Hint: Break statements only work in loops. Fix: Move inside loop. |
| E403 | Continue outside loop | Hint: Continue statements only work in loops. Fix: Move inside loop. |
| E404 | Return outside function | Hint: Return found in global scope. Fix: Move inside a function body. |
| E405 | Invalid use of ‘self’ | Hint: self used inside static method or free function.Fix: Remove self or make it an instance method. |
| E406 | Invalid superclass | Hint: Inheriting from a final or non-class type. Fix: Check inheritance hierarchy. |
| E407 | Cyclic inheritance | Hint: Class A extends B, B extends A. Fix: Break the inheritance cycle. |
| E408 | Abstract method missing | Hint: Concrete class must implement abstract methods. Fix: Implement the missing method. |
| E409 | Invalid override | Hint: Overriding method signature does not match parent. Fix: Match arguments and return types. |
| E410 | Dead code detected | Hint: Code after return/throw is unreachable. Fix: Remove the code or fix flow. |
| E411 | Unreachable code | Hint: Logic ensures this block never runs. Fix: Review logic conditions. |
| E412 | Unused variable | Hint: Variable defined but never read. Fix: Remove variable or use _ prefix. |
| E413 | Unused function | Hint: Function defined but never called. Fix: Remove or export the function. |
| E414 | Invalid constant | Hint: Constant value must be known at compile time. Fix: Don’t use runtime function calls in consts. |
| E415 | Mutability violation | Hint: Modifying a const or immutable reference. Fix: Check mutability rules. |
Issues related to loading external code.
| Code | Description | Hints & Suggestions |
|---|---|---|
| E500 | Module not found | Hint: Check file path. Fix: Install package or fix path. |
| E501 | Circular import | Hint: Module A imports B, B imports A. Fix: Refactor shared code into Module C. |
| E502 | Invalid import path | Hint: Path format is wrong. Fix: Use correct separators (e.g., :: or /). |
| E503 | Symbol not found | Hint: Name not exported from module. Fix: Check module exports or spelling. |
| E504 | Conflicting imports | Hint: Two imports share the same name. Fix: Use as to rename one import. |
| E505 | Module parse error | Hint: Imported file has syntax errors. Fix: Fix errors in the imported file. |
| E506 | Module type error | Hint: Imported file has type errors. Fix: Fix errors in the imported file. |
| E507 | Invalid module structure | Hint: mod.q or folder structure incorrect.Fix: Follow module system conventions. |
| E508 | Package not found | Hint: External dependency missing. Fix: Run package manager install. |
| E509 | Version conflict | Hint: Dependencies require different versions. Fix: Update dependencies to compatible versions. |
Errors specific to quantum logic.
| Code | Description | Hints & Suggestions |
|---|---|---|
| E600 | Invalid quantum gate | Hint: Gate name unknown (e.g., Hadamard vs H).Fix: Check standard gate library. |
| E601 | Invalid gate params | Hint: Phase/Angle parameter missing or wrong type. Fix: Provide correct float parameters. |
| E602 | Incompatible qubit op | Hint: Operation cannot be applied to these qubits. Fix: Check connectivity/topology. |
| E603 | Invalid control config | Hint: Control qubit cannot be target. Fix: Ensure distinct control/target qubits. |
| E604 | Register too large | Hint: Simulators cannot handle too many qubits. Fix: Reduce qubits or use cloud backend. |
| E605 | Invalid initial state | Hint: State vector must be normalized. Fix: Normalize the input vector. |
| E606 | Uninitialized qubit | Hint: Measuring qubit before preparation. Fix: Initialize to |0> or |1>. |
| E607 | Invalid dagger op | Hint: Cannot compute adjoint of this operation. Fix: Ensure operation is unitary. |
| E608 | Gate arity mismatch | Hint: Applying 2-qubit gate to 1 qubit. Fix: Check gate definition. |
| E609 | Invalid tensor product | Hint: Dimension mismatch in tensor product. Fix: Check matrix dimensions. |
| E610 | Normalization error | Hint: Sum of probabilities != 1. Fix: Re-normalize state vector. |
| E611 | Invalid circuit | Hint: Circuit has open wires or loops. Fix: Validate circuit topology. |
| E612 | Superposition error | Hint: Failed to create superposition. Fix: Check Hadamard usage. |
| E613 | Entanglement error | Hint: CNOT/Entangling gate failed. Fix: Check control/target setup. |
| E614 | Decoherence detected | Hint: Simulation exceeded coherence time. Fix: Reduce circuit depth. |
Low-level errors occurring during code generation.
| Code | Description | Hints & Suggestions |
|---|---|---|
| E700 | LLVM internal error | Fix: Report this bug to the compiler developers. |
| E701 | Codegen failed | Fix: Simplify code or check for unsupported structures. |
| E702 | Optimization failed | Fix: Disable specific optimization flags. |
| E703 | Linking error | Hint: Missing external libraries. Fix: Check linker paths. |
| E704 | Invalid target | Hint: Target architecture unknown. Fix: Check --target flag. |
| E705 | Unsupported feature | Hint: Feature not available on this CPU/QPU. Fix: Use a different target. |
| E706 | Assembly error | Hint: Error in generated assembly. Fix: Check inline assembly usage. |
| E707 | Object file error | Hint: Corrupt object file. Fix: Clean and rebuild. |
| E708 | Debug info error | Hint: DWARF generation failed. Fix: Compile without debug info ( -r). |
| E709 | ABI mismatch | Hint: Linking C and Quantica with different ABIs. Fix: align calling conventions. |
| E710 | Platform unsupported | Hint: OS not supported. Fix: Switch to Linux/macOS/Windows. |
Errors occurring when interfacing with physical quantum backends.
| Code | Description | Hints & Suggestions |
|---|---|---|
| E800 | Backend not available | Hint: Qiskit/Cirq/Braket not found. Fix: Install required backend. |
| E801 | Device not found | Hint: Quantum chip name is incorrect. Fix: List available devices. |
| E802 | Connection error | Hint: No internet or API down. Fix: Check network connection. |
| E803 | Auth failed | Hint: API Token invalid or expired. Fix: Refresh API key. |
| E804 | Job submission failed | Hint: Queue full or payload invalid. Fix: Retry later or validate circuit. |
| E805 | Job execution error | Hint: Runtime error on QPU. Fix: Check job logs. |
| E806 | Result retrieval failed | Hint: Network timeout getting results. Fix: Retry fetching job ID. |
| E807 | Unsupported gate | Hint: Hardware doesn’t support this native gate. Fix: Transpile to basis gates. |
| E808 | Hardware timeout | Hint: Job sat in queue too long. Fix: Increase timeout setting. |
| E809 | Calibration error | Hint: QPU calibration data stale. Fix: Wait for recalibration. |
| E810 | Noise model error | Hint: Noise params invalid. Fix: Check thermal/depolarizing params. |