# Troubleshooting

> Real errors from qsolve lint, validation gates, the SDK and failed runs, with the cause of each and how to fix it, listed by the code or message you see.

Source: https://qsolve.omlabs.co/docs/build/troubleshooting
Updated: 2026-11-13

Find the message or code you see below. Lint codes come from `qsolve lint` and the submission's lint stage, gate messages from `qsolve test` and the gates stage, and error codes from a failed run. Messages are quoted as Qsolve prints them.

## Lint codes

The complete reference, with exact triggers, is [Lint codes](/docs/build/lint-codes). Errors (`E`) fail lint and reject a submission. Warnings (`W`) do not. The short list:

| Code | Message | Fix |
|---|---|---|
| `E001` | qsolve.yaml not found at the repository root | Put `qsolve.yaml` at the root of the repository, or enter its folder in the **Folder** field. |
| `E002` | invalid workflow definition: ... | The manifest or a schema file is invalid. `qsolve validate .` shows the field and reason. |
| `E010` | symbolic links are not allowed | Replace the link with a real file. |
| `E011` | too many files (n > 500), or repository too large | Stay under 500 files and 20 MB. Remove data you do not need. |
| `E012` | file looks like a credential; remove it and rotate the secret | Delete `.env`, `*.pem`, `*.key`, `id_rsa*`, `credentials*.json` or `.netrc` and revoke the credential. |
| `E013` | possible private key, cloud or GitHub token, payment-style secret or quantum-provider token committed | Remove it and rotate the secret. A workflow never needs credentials. |
| `E020` | invalid JSON Schema: ... | Fix the schema. It must be valid draft-07. |
| `E021` | `pattern` or `patternProperties` is not allowed; only local `#/...` `$ref` values are allowed; format `regex` is not allowed | Use `enum`, `minLength` or `maxLength`; point `$ref` at `#/definitions/...`. |
| `E022` | schema is too large | Keep each schema under 256 KB. |
| `E023` | example input unreadable, or does not match the input schema | Fix the example or the schema. `qsolve validate .` shows the failing path. |
| `E024` | at least one example input is required | List a file under `inputs.examples`. |
| `E030` | module not found in the repository, or the class is not defined in it | Check `entrypoint`. `src.workflow:MaxCut` needs `src/workflow.py` defining `class MaxCut`. |
| `E031` | syntax error, or cannot parse Python | Fix the syntax error at the line shown. |
| `E040` | imports 'x', which is not available in the runtime | Import only the standard library and `qsolve`, NumPy, SciPy, scikit-learn, Qiskit, Qiskit Aer, PySCF, pydantic, jsonschema, PyYAML, typer and rich. |
| `E050` | benchmarks/cases.yaml is required | Add the file; see [Benchmarks](/docs/build/benchmarks). |
| `E051` | a license identifier is required | Set `license` in the manifest. |
| `E052` | hardware_cases are invalid, or a hardware case has no `ibm:<device>` target | Fix the entry; see [Hardware cases](/docs/build/benchmarks). |
| `E053` | more than three hardware_cases | Keep at most three. |
| `E054` | hardware_cases need `qpu: [ibm]` under targets | Add `ibm` to `targets.qpu` in the manifest. |
| `W041` | imports `subprocess`, `socket`, `ctypes`, `pickle`, `marshal`, `shelve` or `multiprocessing`, or calls `eval`, `exec`, `compile` or `__import__` | Blocked or useless at run time, and flagged for review. Remove them. |
| `W042` | imports 'x', pinned in requirements.lock but not available | The run rejects the import. Remove the dependency; see [Project layout](/docs/build/project-layout). |
| `W043` | imports a module by name at run time | Not checked by lint. Prefer ordinary imports. |
| `W051` | no LICENSE file found | Add `LICENSE`. |
| `W060` | no README.md | Add one saying what the workflow solves and its limits. |

## Manifest errors

`qsolve validate` prints `Invalid workflow:` followed by the field and the reason.

| Message | Cause |
|---|---|
| `No qsolve.yaml in <dir>` | Wrong directory. |
| `Field required` (with a field name) | A required field is missing. |
| `Extra inputs are not permitted` (with a field name) | An unknown or misspelled field. |
| `Input should be a valid string` on `version` | YAML read `1.0` as a number. Write `1.0.0`. |
| `name must be lowercase letters, digits and dashes (2-63 chars)` | Fix the name. |
| `version must be semver, e.g. 0.1.0` | Use three numeric parts. |
| `entrypoint must look like 'package.module:ClassName'` | Fix the entrypoint. |
| `declare exactly one method with role 'quantum'` (or `'reference'`) | Declare exactly one of each. |
| `method ids must be unique` | Rename a method. |
| `List should have at least 2 items after validation` on `methods` | Declare a quantum method and a reference. |
| `parameter names must be unique` | Rename a parameter. |
| `parameter 'layers' must be <= 6.0` (at load time) | The `default` breaks the parameter's own bounds. |
| `schema path escapes workflow directory: ...` | A schema path points outside the repository. |

## Input and run errors

These appear locally from `qsolve run` and `qsolve estimate` as `Error: <message>`, and in a failed run on the platform.

| Message | Cause and fix |
|---|---|
| `Invalid input at <path>: <message>` | The input does not match `schemas/input.json`. Fix it at that path. |
| `unknown parameters: [...]` | An override names a parameter the manifest does not declare. |
| `parameter 'x' must be ...` | A value breaks its declared type, range or choices. See [Parameters](/docs/build/parameters). |
| `Problem has N variables; this workflow supports at most M (notes)` | `size()` is above the `envelope`. Reduce the problem, or raise the envelope if your code handles it. |
| `Cannot load the workflow 'x': ...` | The entrypoint cannot be imported. Look for an import error in your module. |
| `'x' must be a subclass of qsolve.Workflow` | The entrypoint class does not inherit from `Workflow`. |
| `Could not set up the problem from this input: ...` | A `ValueError`, `KeyError`, `TypeError` or `IndexError` escaped `__init__`. Validate the input there and raise `WorkflowError` with a clear message. |
| `method 'x' is declared in the manifest but the workflow has no 'classical_x' method` | Add the method. Dashes in the id become underscores. |
| `the quantum method or the reference produced no result: ...` | One was unavailable or returned an invalid value. The reason follows. |
| `answer() failed on the quantum result: ...` | Your `answer()` raised. |
| `Workflow produced an invalid answer: ...` | The answer does not match `schemas/output.json`. |
| `evaluate() failed on a method's solution: ...` | Your `evaluate` raised something other than `InvalidSolution`. |
| `a classical method tried to run a circuit: only the quantum method may use the backend` | `reference` or `classical_*` used `ctx.backend`, `ctx.sampler` or `ctx.estimator`. |
| `report_mitigation cites circuits [...], but N were sent so far` | A dispatch index does not exist. Take it from `metadata["qsolve"][k]["dispatch"]`. |
| `report_mitigation: the distribution must hold finite, non-negative weights` | Clean the distribution. |
| `report_mitigation: kept is a share of shots between 0 and 1` | Fix `kept`. |

A method shown as unavailable on a result carries one of these reasons: `failed: <ExceptionType>: <message>` for a classical method that crashed; the text of your `MethodUnavailable` or `InvalidSolution`; "it reported a value that is not a finite number"; "it reported an error bar that is not a finite, non-negative number"; "evaluate() returned a value that is not a finite number"; "it sent circuits to the quantum backend, which only the quantum method may do".

## Validation gate messages

| Gate | Message | Cause and fix |
|---|---|---|
| `example_inputs` | `<file>: Invalid input at ...` or `0 valid` | An example fails the schema, or none is listed. |
| `benchmark_cases` | `0 cases defined` | Add cases to `benchmarks/cases.yaml`. |
| `methods_declared` | `no methods declared: add methods: ...` | Declare a quantum method and a reference. |
| `fidelity_checked` | `no case sets expect.min_fidelity on a noisy target (target: fake:fez@1.6)` | Add a `fake:` case with `min_fidelity`. |
| `cases_pass` | `n/m passed`, with `FAIL ...` per case | See the case messages below. |
| `reproducible` | `result differs under same seed at result.<path>` | Something is not seeded. Use `ctx.seed` for every random generator and avoid hash- or set-dependent iteration order. |
| `reproducible` | `the rerun with the same seed failed: ...` | The same input failed the second time. |
| `estimate_honest` | `estimated N circuits, the run sent M` (or `shots`) | Your `estimate()` is off by more than a factor of two. Count what each parameter makes the run send. |
| `estimate_honest` | `estimate() failed: ...` | Your `estimate()` raised. |

Case messages, shown beside `FAIL`:

| Message | Meaning |
|---|---|
| `<ExceptionType>: ...` | The case raised. |
| `no headline metric: quantum and reference could not be compared` | The quantum method or the reference had no value. |
| `method x failed: ...` | A method crashed or was unavailable. |
| `method x claimed A, its solution gives B` | The objective you reported differs from `evaluate(solution)`. Fix the method or `evaluate`. |
| `quantum method x sent no circuit to the backend` | The quantum method must send circuits through `ctx`. |
| `no mitigation numbers reported` | A case set `min_fidelity` or `min_postselection`, but the run has no scorable circuits or no report. |
| `only N% of the quantum method's shots could be scored against an ideal output` | Circuits over 20 qubits or with mid-circuit measurement cannot be scored. Fidelity bounds need 90% coverage. |
| `fidelity F < B` | The mitigated fidelity is below `min_fidelity`. Improve mitigation or lower the bound to what the circuit reaches. |
| `post-selection P < B` | The share of shots kept is below `min_postselection`. |
| `N two-qubit gates > M` | A circuit exceeds `max_two_qubit_gates`. Make it shallower. |
| `no circuit size reported` | `max_two_qubit_gates` was set but no circuit was recorded. |

A case that misses `max_gap` or `max_abs_error` fails with no message; the table shows its gap. The case rules are in [Benchmarks](/docs/build/benchmarks).

## Submission and run errors

| Where | Message or code | Meaning |
|---|---|---|
| Submission | `Only https://github.com/<owner>/<repo> repositories are supported.` | Use an HTTPS GitHub address of the form shown. |
| Submission | `No qsolve.yaml in the folder '<folder>' of this repository at that commit.` | The folder is wrong or does not exist on that branch. Check the spelling, or leave the field empty if `qsolve.yaml` is at the root. |
| Submission | `Could not resolve '<ref>' in this repository` | The branch or tag does not exist, or the repository is private and not connected. See [Private repositories](/docs/build/private-repositories). |
| Submission | `The repository contains symbolic links, which are not allowed.` or `...submodules...` | Remove them. |
| Submission | `Fetching the repository timed out.` or `repository exceeds 50 MB` | Reduce the repository. |
| Submission | `Version X of <name> already exists with different content; bump the version ...` | See [Versioning](/docs/build/versioning). |
| Submission | `Case 'x': input_file ...` or `Case 'x': input does not match the input schema ...` | Fix the case named in the message; see [Benchmarks](/docs/build/benchmarks). |
| Submission | `Parameter 'shots' has max N, above the platform cap of 100,000 ...` | Lower the `shots` default or max. |
| Run | `shots_too_high` | The run's `shots` is above 100,000 per circuit. |
| Submission | `the benchmark run timed out` or `ran out of memory` | Speed up the cases or raise `resources` in the manifest, within the validation caps. |
| Run | `run_too_long` | The predicted `runtime_s` exceeds `resources.timeout_s`. |
| Run | `timeout` | The run exceeded `resources.timeout_s`. |
| Run | `out_of_memory` | The run exceeded `resources.memory_mb`. |
| Run | `workflow_crashed` | Your code raised an unexpected exception. The log tail is kept with the run. |
| Run | `budget_exhausted` | The run needed more credits than were set aside for it, so it was stopped. Your `estimate()` was too low. |
| Run | `target_not_supported` | The run asked for a target the manifest's `targets` does not list. |

## Local environment errors

| Message | Fix |
|---|---|
| `Install the ibm extra: pip install 'qsolve-sdk[ibm]'` | Needed for `fake:` and `ibm:` targets. |
| `no fake device 'x' (e.g. fez, marrakesh, torino)` | Use a device name that `qiskit_ibm_runtime` ships a fake for. |
| `noise scale must be between 1 and 10` | Use `@1` to `@10`. |
| `QSOLVE_IBM_TOKEN is not set` | Set it to run on `ibm:<device>` locally. |
| `Unknown target 'x'. Use sim-cpu, sim-gpu, ibm:<device> or fake:<device>[@scale].` | Fix the target string. |

## Passes locally, fails on the platform

The difference is almost always the environment, not the SDK. Check in order:

1. Run `qsolve lint .`. It flags imports the platform cannot satisfy; `qsolve test` does not.
2. Make sure everything your code reads is in the repository. Files in `tests/` and caches are not shipped.
3. Remove paths outside the repository and network calls. A run sees only the repository and a scratch directory, with no network.
4. Check run time. A fast machine hides slow code; validation has a limit from `resources.timeout_s`, raised to at least 300 and capped at 7200 seconds.
5. Check threading. Runs use one BLAS thread, so results that depend on summation order on a multi-core laptop can differ in the last digits. Differences beyond relative 1e-8 fail `reproducible`.