Troubleshooting guide

​

Authentication errors

​

API key invalid

Error: 401 Unauthorized - Invalid API key

1. Check your API key is correct: echo $QWED_API_KEY
2. Make sure the value is not a placeholder — qwed init ignores common dummy values like your-api-key, changeme, placeholder, and xxx. Replace them with a real key.
3. Regenerate key at cloud.qwedai.com
4. Ensure no extra spaces or newlines

# Correct
client = QWEDClient(api_key="qwed_live_abc123...")

# Wrong - has newline
client = QWEDClient(api_key="qwed_live_abc123...\n")

​

Rate limit exceeded

Error: 429 Too Many Requests

• Free tier: 100 requests/minute
• Pro tier: 1,000 requests/minute
• Enterprise: Unlimited

from qwed_sdk import QWEDClient
import time

client = QWEDClient()

# Implement backoff
for attempt in range(3):
    try:
        result = client.verify("2+2=4")
        break
    except RateLimitError:
        time.sleep(2 ** attempt)

​

Verification failures

​

Math: floating-point precision

# Fails due to floating point
result = client.verify_math("0.1 + 0.2 = 0.3")
# False! (0.1 + 0.2 = 0.30000000000000004)

result = client.verify_math("0.1 + 0.2 = 0.3", tolerance=1e-10)
# True

​

Logic: unsatisfiable constraints

Error: No satisfying assignment found

# This is unsatisfiable
"(AND (GT x 10) (LT x 5))"  # x > 10 AND x < 5 - impossible!

# Check satisfiability first
result = client.check_satisfiability("(AND (GT x 10) (LT x 5))")
print(result.satisfiable)  # False

​

Stats: Internal verification error

Error: Internal verification error

1. Verify your query is a valid statistical question (e.g., “What is the mean of column X?”)
2. Check that the column names in your query match the columns in your data
3. If the issue persists, check the server-side logs for the exception type

​

Code: timeout

Error: Verification timeout after 30s

1. Increase timeout: client.verify_code(code, timeout=60)
2. Simplify code (reduce loops, recursion)
3. Use bounded verification

​

CLI issues

​

qwed init fails with “attempt to write a readonly database”

sqlite3.OperationalError: attempt to write a readonly database

pip install --upgrade qwed

cd ~/my-project
qwed init

​

qwed init fails with “Server identity check failed”

  [x] Server identity check failed: server identity check failed: the running server holds a different jwt and lookup secret(s) than this project. ...

• The proofs don’t match.
• The server returns 404 (an older server without the endpoint) or another non-200 status.
• The response is malformed.
• The server is unreachable.
• The local secrets are missing.

• “…holds a different jwt and/or lookup secret(s)…” — a stale QWED server (started with different secrets) or an unrelated process is listening on the port. Stop that process, then re-run qwed init; it starts a fresh server with the secrets from your .env.
• “…the server did not prove its secrets…” (non-200) — a 404 means the server predates this endpoint: upgrade it. A 503 means the intended server is running with no secrets configured: set QWED_JWT_SECRET_KEY and QWED_API_KEY_LOOKUP_SECRET in its environment, then restart. Any other status can indicate a foreign listener: stop whatever holds the port and re-run qwed init.
• “…could not reach the identity endpoint…” — no server is listening (or it died after the health check), or --server-url points at the wrong host/port. Re-run qwed init so it starts a fresh server, or point --server-url at the running one.
• “…unreadable identity response…” — a live-but-broken server is answering, and a plain re-run of qwed init reuses a healthy-looking running server, so the same check fails again. Stop or restart the responding process, then re-run qwed init.
• Local secrets are missing — re-run qwed init; it generates and persists fresh secrets before the handshake.

​

Gemini provider issues

​

Missing google-generativeai package

ImportError: google-generativeai package required for Gemini integration.

pip install qwed google-generativeai

​

Gemini API key not found

ValueError: Gemini API key not found. Set GOOGLE_API_KEY env var or run: qwed init

export GOOGLE_API_KEY=your-google-api-key

qwed init

​

Gemini timeout errors

1. Check your network connection to Google’s API servers
2. Break large inputs into smaller parts
3. For image verification, ensure images are under 10 MB

​

Gemini JSON parse errors

ValueError: Failed to parse JSON from Gemini endpoint.

​

SDK issues

​

Import error

ModuleNotFoundError: No module named 'qwed_sdk'

pip install qwed
# or
pip install qwed-sdk

​

Async not working

# Wrong - missing await
result = client.verify("2+2=4")  # Returns coroutine, not result

# Sync client
from qwed_sdk import QWEDClient
client = QWEDClient()
result = client.verify("2+2=4")

# Async client
from qwed_sdk import QWEDAsyncClient
async with QWEDAsyncClient() as client:
    result = await client.verify("2+2=4")  # Must await!

​

DSL syntax errors

​

Unknown operator

SECURITY BLOCK: Unknown operator 'CHECK_IF_VALID'

# Wrong
"(CHECK_IF_VALID x)"

# Correct
"(GT x 0)"

​

Missing parentheses

SyntaxError: Missing closing ')'

# Wrong - 3 open, 2 close
"(AND (GT x 5) (LT y 10)"

# Correct - 3 open, 3 close
"(AND (GT x 5) (LT y 10))"

​

Performance issues

​

Slow verification

1. Complex expressions with many variables
2. Large code files
3. Deep recursion in symbolic execution

# 1. Use caching
from qwed_sdk import QWEDClient
client = QWEDClient(cache=True)

# 2. Batch requests
results = client.verify_batch([
    {"query": "2+2=4"},
    {"query": "3+3=6"},
])

# 3. Use async for parallel requests
async def verify_many(queries):
    async with QWEDAsyncClient() as client:
        tasks = [client.verify(q) for q in queries]
        return await asyncio.gather(*tasks)

​

High memory usage

# For large batch operations
for result in client.verify_batch_stream(large_list):
    process(result)
    # Processes one at a time, not all in memory

​

Common error codes

​

Getting help

1. Documentation: docs.qwedai.tech
2. GitHub Issues: github.com/QWED-AI/qwed-verification/issues
3. Email: support@qwedai.com
4. Intercom: Chat widget on docs site

​

Debug mode

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

from qwed_sdk import QWEDClient
client = QWEDClient()

# Now you'll see detailed request/response logs
result = client.verify("2+2=4")