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.

TOML manifest errors

”schema_version ’…’ is not supported”

Your qubithub.toml specifies an unrecognized schema version. Use a supported version:

schema_version = "1.1.0"

“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.