Troubleshooting

Common issues and their solutions when using SoftQCOS.

Installation Issues

pip install fails

Error:

ERROR: Could not find a version that satisfies the requirement softqcos-sdk

Solutions:

1. Check Python version (requires 3.10+):

python --version
# Should be 3.10 or higher

2. Upgrade pip:

pip install --upgrade pip

3. Use explicit Python:

python3.11 -m pip install softqcos-sdk

4. Install from source:

pip install git+https://github.com/softquantus/softqcos-sdk.git

Import error: No module named 'softqcos_sdk'

Error:

ModuleNotFoundError: No module named 'softqcos_sdk'

Solutions:

1. Verify installation:

pip show softqcos-sdk

2. Check virtual environment:

which python
# Should point to your venv

3. Reinstall:

pip uninstall softqcos-sdk
pip install softqcos-sdk

Dependency conflicts

Error:

ERROR: Cannot install softqcos-sdk because these package versions have conflicting dependencies

Solutions:

1. Create fresh virtual environment:

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or: .venv\Scripts\activate  # Windows
pip install softqcos-sdk

2. Use pip's resolver:

pip install softqcos-sdk --use-feature=fast-deps

---

Authentication Issues

"Invalid API key" error

Error:

AuthenticationError: Invalid API key

Causes & Solutions:

Cause	Solution
Typo in API key	Double-check key in portal
Key revoked	Generate new key in portal
Wrong environment	Use production key for production
Expired key	Regenerate in portal

Debug:

import os
from softqcos_sdk import QCOSClient

# Check if key is set
api_key = os.environ.get("SOFTQCOS_API_KEY", "NOT SET")
print(f"Key starts with: {api_key[:10]}...")

# Test authentication
client = QCOSClient(api_key=api_key)
try:
    health = client.health()
    print(f"✅ Connected: {health}")
except Exception as e:
    print(f"❌ Error: {e}")

"Unauthorized" for Azure Quantum

Error:

AzureQuantumError: Unauthorized - Azure Quantum access not enabled

Solution: Your plan may not include Azure Quantum access. Check your plan at portal.softquantus.com/settings/billing.

---

Execution Issues

"Circuit validation failed"

Error:

CircuitValidationError: Invalid QASM: syntax error at line 5

Common Causes:

1. Missing includes:

// ❌ Wrong
OPENQASM 2.0;
qreg q[2];
h q[0];  // 'h' not defined

// ✅ Correct
OPENQASM 2.0;
include "qelib1.inc";  // Include standard gates
qreg q[2];
h q[0];

2. Missing semicolons:

// ❌ Wrong
h q[0]
cx q[0], q[1]

// ✅ Correct
h q[0];
cx q[0], q[1];

3. Invalid gate arguments:

// ❌ Wrong
rx(pi) q[0];  // 'pi' not a valid float in QASM 2.0

// ✅ Correct
rx(3.14159) q[0];

Validate before submitting:

from softqcos_sdk import QCOSClient

client = QCOSClient()

# Validate circuit
validation = client.validate(circuit)
if not validation.valid:
    print(f"Errors: {validation.errors}")

"Circuit too large for backend"

Error:

CircuitValidationError: Circuit requires 30 qubits, backend supports 25

Solutions:

1. Check backend limits:

backends = client.list_backends()
for b in backends:
    print(f"{b.name}: {b.max_qubits} qubits")

2. Use a larger backend:

# Use Aer simulator for up to 32 qubits
result = client.execute(qasm=circuit, backend="aer", shots=1024)

3. Optimize circuit:

# Optimization may reduce qubit requirements
optimized = client.optimize(circuit, target="ionq")

Timeout errors

Error:

TimeoutError: Job did not complete within 300 seconds

Solutions:

1. Increase timeout:

result = client.execute(
    qasm=circuit,
    shots=1024,
    timeout=600  # 10 minutes
)

2. Use async mode:

# Submit and poll separately
job = client.submit(qasm=circuit, shots=1024)

# Check status
status = client.get_job_status(job.job_id)
print(f"Status: {status}")

# Get result when ready
result = client.get_result(job.job_id)

3. For Azure Quantum: Queue times can be long

# Check queue status
providers = client.azure_quantum.list_providers()
for p in providers:
    print(f"{p.name}: queue ~{p.estimated_queue_time}")

---

Rate Limiting

"Rate limit exceeded"

Error:

RateLimitError: Rate limit exceeded. Retry after 30 seconds.

Solution - Automatic retry:

from softqcos_sdk import QCOSClient

# SDK handles retries automatically
client = QCOSClient(
    max_retries=3,
    retry_delay=1.0
)

Solution - Manual handling:

from softqcos_sdk import QCOSClient, RateLimitError
import time

client = QCOSClient()

for circuit in circuits:
    while True:
        try:
            result = client.execute(qasm=circuit, shots=1024)
            break
        except RateLimitError as e:
            print(f"Rate limited. Waiting {e.retry_after}s...")
            time.sleep(e.retry_after)

Solution - Batch processing:

# More efficient than individual requests
results = client.execute_batch(
    circuits=circuits,
    shots=1024
)

---

Azure Quantum Issues

"Provider unavailable"

Error:

ProviderUnavailableError: ionq.aria-1 is currently unavailable

Causes:

• Provider maintenance
• High demand / capacity limits
• Regional outage

Solutions:

1. Check provider status:

providers = client.azure_quantum.list_providers()
for p in providers:
    print(f"{p.name}: {'✅' if p.available else '❌'}")

2. Use alternative target:

# Try simulator if QPU unavailable
targets = ["ionq.aria-1", "ionq.simulator"]
for target in targets:
    try:
        result = client.azure_quantum.execute(circuit, target, 100)
        break
    except ProviderUnavailableError:
        continue

"Insufficient credits"

Error:

QuotaExceededError: Insufficient Azure Quantum credits

Solutions:

1. Check remaining credits:

usage = client.usage.get_azure_quantum_summary()
print(f"Remaining: €{usage.remaining_credits_eur:.2f}")

2. Use simulator instead (free):

result = client.azure_quantum.execute(
    circuit=circuit,
    target="ionq.simulator",  # Free
    shots=1024
)

3. Add credits at portal.softquantus.com/billing

Jobs stuck in queue

Symptom: Job status stays "queued" for hours

Diagnosis:

job = client.azure_quantum.get_job(job_id)
print(f"Status: {job.status}")
print(f"Position in queue: {job.queue_position}")
print(f"Estimated wait: {job.estimated_wait_time}")

Solutions:

1. Wait - Some providers have long queues
2. Cancel and use simulator:

client.azure_quantum.cancel_job(job_id)

3. Try different provider:

# Rigetti often has shorter queues
result = client.azure_quantum.execute(circuit, "rigetti.qpu.ankaa-2", 100)

---

Performance Issues

Slow execution times

Causes & Solutions:

Cause	Solution
Large circuit	Optimize first
Too many shots	Reduce shots
Network latency	Use async mode
Server load	Try off-peak hours

Optimization:

# 1. Optimize circuit
optimized = client.optimize(circuit)

# 2. Use appropriate shots
# Most applications: 1024-4096 shots sufficient
result = client.execute(qasm=optimized.circuit, shots=1024)

# 3. Use async for multiple circuits
async def run_all(circuits):
    async with AsyncQCOSClient() as client:
        tasks = [client.execute(c, 1024) for c in circuits]
        return await asyncio.gather(*tasks)

Memory issues with large batches

Error:

MemoryError: Unable to allocate array

Solutions:

1. Process in chunks:

def chunked_execute(circuits, chunk_size=100):
    results = []
    for i in range(0, len(circuits), chunk_size):
        chunk = circuits[i:i+chunk_size]
        chunk_results = client.execute_batch(chunk, shots=1024)
        results.extend(chunk_results)
    return results

2. Use streaming:

# Process results as they arrive
for result in client.execute_batch_stream(circuits, shots=1024):
    process(result)
    # Result is discarded after processing

---

CLI Issues

"softqcos: command not found"

Solutions:

1. Install CLI:

pip install softqcos-sdk[cli]

2. Check PATH:

python -m softqcos --version
# If this works, add to PATH

3. Use Python module:

python -m softqcos execute circuit.qasm

CLI authentication

Error:

Error: No API key configured

Solution:

# Set via environment
export SOFTQCOS_API_KEY=your-api-key

# Or configure via CLI
softqcos auth login

# Or pass directly
softqcos execute circuit.qasm --api-key your-api-key

---

Getting More Help

Debug mode

Enable verbose logging:

import logging
logging.basicConfig(level=logging.DEBUG)

from softqcos_sdk import QCOSClient
client = QCOSClient()

Collect diagnostics

from softqcos_sdk import diagnostics

report = diagnostics.collect()
print(report)

# Save for support
report.save("diagnostics.json")

Contact support

Include in your support request:

1. SDK version: pip show softqcos-sdk
2. Python version: python --version
3. OS: Windows/macOS/Linux
4. Full error message with traceback
5. Minimal reproduction code
6. Diagnostics report (if possible)

Support channels:

• 📧 Email: support@softquantus.com
• 💬 Discord: discord.gg/softquantus
• 🐛 GitHub: Issues