Troubleshooting

Installation

`pip install qubithub-sdk` fails

Ensure you have Python 3.11 or later:

python --version

If your system Python is older, use a virtual environment:

python3.11 -m venv .venv
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows
pip install qubithub-sdk

Authentication

”missing bearer token” or “missing api key”

Your request has no authentication credentials. All endpoints currently require JWT bearer tokens:

Log in interactively: qubithub login (the CLI handles tokens automatically)
For scripts, set the environment variable: export QUBITHUB_API_KEY=qh_... (used by the CLI for non-interactive login)

”invalid token” or “token error”

Your JWT token has expired (tokens last 15 minutes). The CLI refreshes automatically, but if you see this in a script:

qubithub logout && qubithub login

For long-running automation, use an API key instead of JWT.

”invalid api key”

The API key doesn’t match any active key. Possible causes:

The key was revoked (qubithub keys list to check)
The key has expired (check expiration date)
You’re using the key prefix (qh_a1b2c3d4) instead of the full key

”Account is inactive”

Your account has been deactivated. Email support@qubithub.co to resolve this.

”forbidden: missing scopes”

Your API key doesn’t have the required scope for this operation. For example, pushing a circuit requires circuit:write. Create a new key with the correct scopes:

qubithub keys create --name "full access" --scopes circuit:read,circuit:write,runs:submit

For a full overview of authentication methods, see the Authentication guide.

Code execution

My circuit works locally but fails on QubitHub

The sandbox is more restrictive than your local environment. If your circuit runs on your machine but fails on QubitHub, check these common differences:

Imports: Only Qiskit, PennyLane, Cirq, NumPy, SciPy, Matplotlib, and select standard library modules are available. No pandas, sklearn, requests, etc.
No file I/O: Functions like open(), numpy.loadtxt(), and matplotlib.savefig() are blocked. Return results in memory instead.
No dynamic builtins: eval, exec, compile, getattr, setattr are blocked. Use direct attribute access and static code.
No network: The sandbox cannot make HTTP requests or install packages.
Code length: Maximum 5,000 characters.
Timeout: Default 30 seconds (configurable up to 300 in qubithub.toml).

”Import of ’…’ is not allowed”

The sandbox only permits a curated set of imports. Allowed packages:

Quantum: qiskit, qiskit_aer, pennylane, cirq
Scientific: numpy, scipy, matplotlib
Standard library: math, cmath, random, json, collections, itertools, functools, typing, dataclasses

If you see Import of 'subprocess' is not allowed or similar, your code is using a blocked module. Rewrite to avoid system-level imports.

”Reference to ’…’ is not allowed (dangerous builtin)”

The sandbox blocks builtins that can bypass security restrictions: eval, exec, compile, open, __import__, getattr, setattr, globals, locals, and others.

Instead of open(): Return results as the function’s return value — the platform captures stdout and return data automatically.
Instead of getattr(obj, 'attr'): Use direct attribute access: obj.attr.
Instead of eval() / exec(): Write the logic statically in your circuit code.

”Access to ’…’ is not allowed for security reasons”

Certain attributes are blocked to prevent sandbox escapes — for example, accessing __subclasses__, __code__, or __globals__. Stick to the public API of allowed packages.

”Import of ’…’ is not allowed (file I/O is prohibited)”

File I/O functions from allowed packages are blocked individually. This includes numpy.loadtxt, numpy.save, scipy.loadmat, matplotlib.savefig, and matplotlib.imread. The sandbox filesystem is read-only — return results in memory instead of writing files.

”Execution timed out after N seconds”

Your circuit took longer than the configured timeout. This usually means the circuit needs more time or resources than the defaults allow. To fix:

Reduce shots: Fewer shots means faster execution. Try --shots 100 for a quick test (though results will be noisy — 1,024+ shots give reliable statistics).
Reduce qubit count: Statevector simulation doubles in memory for each added qubit. Circuits above ~20 qubits can become very slow or exceed the 512 MB memory limit.
Increase timeout: Set timeout_seconds in your qubithub.toml [execution] section (up to 300).

”Code execution is unavailable: Docker sandbox is required but not accessible”

The platform requires Docker for code execution and it’s currently unreachable. This is a server-side issue — no action needed on your end. Circuit execution will resume once the infrastructure is restored.

”Code exceeds maximum length of N characters”

Circuit code is limited to 5,000 characters for the demo endpoint. Split complex logic across helper functions or reduce inline comments to stay within the limit.

Run failure error classes

When a run finishes in failed state, the run page shows a coloured badge with a short class name and a one-line hint. The badge maps a wide range of raw exceptions to one of six user-facing classes so the cause is immediately scannable without reading a stack trace.

Badge	What it means
Circuit File Missing	The platform couldn’t load your circuit code from storage
Parse Error	The circuit definition or manifest couldn’t be parsed
Execution Timeout	The sandbox killed the run for exceeding its time limit
Backend Unavailable	The selected backend or framework isn’t available
Quota Exceeded	You’ve hit a usage limit
Internal Error	Something went wrong on our side

The raw exception message is still preserved on the run page below the badge — the class is for scanning, the message is for diagnosing.

Circuit File Missing

Triggers: The execution path resolved a circuit row in the database but couldn’t read the backing file from storage — for example, circuit.py was uploaded but the storage write was partial, or a file was deleted out-of-band from the database row.

What to do: If it’s a circuit you own, re-push it: qubithub circuits push. If it’s someone else’s circuit, the owner needs to re-upload — report it via Submit Feedback and they’ll be notified.

Parse Error

Triggers: A user-supplied file failed to parse. The platform classifies these as parse errors:

qubithub.toml syntax is invalid
circuit.py is not valid UTF-8
A Qiskit QASM / QPY / JSON ingestion failure on a malformed export
A runner’s own input-validation error (PythonRunnerError, CirqRunnerError, PennyLaneRunnerError)

What to do:

Validate your manifest locally: qubithub circuits metadata -f json
Re-export QASM/QPY from a clean simulation if you suspect file corruption
Check the raw error_message shown below the badge — it identifies the specific parser that rejected the input

Execution Timeout

Triggers: The run exceeded the sandbox’s wall-clock time limit. The default is 30 seconds; configurable up to 300 seconds via qubithub.toml:

[execution]
timeout_seconds = 60

What to do:

Reduce shots — try 100 for a smoke test; ≥1,024 for statistically reliable results
Reduce qubit count — statevector memory doubles per qubit; circuits above ~20 qubits get slow or hit the 512 MB memory cap
Raise timeout_seconds in your manifest up to the platform max of 300

See also: "Execution timed out after N seconds" above for the exact error-message form and per-shot tuning advice.

Backend Unavailable

Triggers: Several distinct causes collapse to this badge:

You selected a hardware backend — hardware integration is on the post-beta roadmap, not live yet
The circuit declares a framework whose runner can’t load — e.g. a missing Python package in the sandbox image (ImportError)
The selected backend type is unknown — the simulator name doesn’t match anything the executor recognises

What to do: Pick a simulator backend that matches your circuit’s framework. The Execute dialog filters backend options to those valid for the circuit’s framework, so picking from that list is the safest path. If you’re certain the backend should work and it’s still failing, Submit Feedback — this case usually means a platform-side fix (missing package in the sandbox image).

Quota Exceeded

Triggers: You’ve hit one of your tier’s monthly usage limits — runs, compute-time, storage, circuits-count, etc.

What to do: Wait for the monthly reset (1st of each month, 00:00 UTC) or Submit Feedback about higher limits. See also: Quotas & storage below for the per-resource limits during beta.

Internal Error

Triggers: The fallback class. Any failure that didn’t match the specific patterns above lands here, with the raw exception preserved in error_message.

What to do: This is almost always a platform-side fault. Submit Feedback and include the run URL — the server-side audit log and Sentry trace are linked by run ID, so we can reconstruct exactly what happened.

TOML manifest errors

”schema_version ’…’ is not supported”

Your qubithub.toml specifies an unrecognized schema version. Use the currently-supported value:

schema_version = "1.0.0"

The parser maintains a SUPPORTED_SCHEMA_VERSIONS allowlist; anything outside it is rejected at validation time. Schema-version bumps will be called out in release notes when they happen.

”name must be lowercase with hyphens only”

Circuit names must match the slug format: lowercase letters, digits, and hyphens only. No spaces, underscores, or uppercase.

# Bad
name = "My_Circuit"

# Good
name = "my-circuit"

”framework must be one of …”

The framework field only accepts: qiskit, pennylane, cirq, braket, or openqasm3. Check for typos or capitalization issues — the value is case-sensitive.

”type must be one of …”

The type field only accepts: circuit, dataset, space, or benchmark.

”project.framework must have a corresponding entry in [implementations]”

If you declare multi-framework support in [implementations], the primary framework must have a matching entry. Either add the implementation or remove the [implementations] section.

General TOML syntax errors

If qubithub circuits push reports a parse error, validate your manifest locally:

qubithub circuits metadata -f json

Common TOML mistakes:

Missing quotes around string values
Using : instead of = for assignments (TOML uses =, not :)
Incorrect array syntax (use ["H", "CX"] not [H, CX])

For the full manifest specification, see the qubithub.toml Reference.

Rate limits

”Rate limit exceeded. Please wait before trying again.”

You’ve hit the API rate limit. During beta, the limit is 60 requests per minute. The response includes a Retry-After header indicating how many seconds to wait. Higher limits will be available on paid tiers.

”Star rate limit exceeded” / “Fork rate limit exceeded”

Star and fork operations have separate, stricter rate limits to prevent abuse. The Retry-After header indicates how long to wait.

Signup and waitlist endpoints have aggressive rate limiting. Wait a few minutes before retrying.

Quotas & storage

”Storage limit exceeded: X/Y MB used”

You’ve reached your tier’s storage quota (100 MB during beta). To free space:

Delete unused circuit versions
Remove large files from datasets
Contact us about higher limits if you need more space

”Circuits limit exceeded: X/Y circuits used”

You’ve hit the maximum circuit count for your tier (10 during beta). Delete unused circuits or contact us about higher limits. The same pattern applies to datasets (5 during beta), spaces (2), and API keys (2).

”Runs limit exceeded” / “Compute time limit exceeded”

Monthly usage limits reset on the 1st of each month at 00:00 UTC. During beta: 100 runs and 5 minutes of compute per month.

”Total upload size exceeds N MB limit”

A single upload batch exceeds the maximum file size (10 MB during beta). Split large uploads into smaller batches.

Organizations

”cannot create repo for different org”

You’re trying to create a resource under an organization you don’t belong to, or don’t have the required role. Check your membership with qubithub orgs list.

”Admin or Owner access required”

Some organization operations (security settings, member management) require Admin or Owner role. Ask your organization owner to update your permissions.