Troubleshooting guide

Common issues and how to resolve them.

Authentication errors

API key invalid

Error: 401 Unauthorized - Invalid API key

Solution:

Check your API key is correct: echo $QWED_API_KEY
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.
Regenerate key at cloud.qwedai.com
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

Solution:

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)

Solution: Use tolerance parameter:

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

Logic: unsatisfiable constraints

Error: No satisfying assignment found

Solution: Check for contradictions:

# 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

The Stats Engine returns this generic message when it fails to generate or translate your query into executable code. QWED masks the actual error details to prevent leaking sensitive information. Solution:

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

Code: timeout

Error: Verification timeout after 30s

Solution:

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

CLI issues

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

sqlite3.OperationalError: attempt to write a readonly database

This error occurs during Step 3 of qwed init. The local server tries to create a bootstrap SQLite database in a directory that is not writable. Common examples include a read-only mount, a container filesystem, or a system-managed path. Solution: Upgrade to QWED v4.0.0 or later:

pip install --upgrade qwed

Starting with v4.0.0, qwed init automatically resolves a writable runtime directory for the database. It uses the current working directory if writable, otherwise falls back to ~/qwed-demo/. No manual intervention is needed. If you cannot upgrade, run qwed init from a writable directory:

cd ~/my-project
qwed init

Gemini provider issues

Missing `google-generativeai` package

ImportError: google-generativeai package required for Gemini integration.

Solution: Install the Gemini SDK alongside QWED:

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

Solution: Set either GOOGLE_API_KEY or GEMINI_API_KEY:

export GOOGLE_API_KEY=your-google-api-key

Or run the setup wizard:

qwed init

Gemini timeout errors

All Gemini API calls have a 30-second timeout. If your requests time out consistently:

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

Gemini JSON parse errors

ValueError: Failed to parse JSON from Gemini endpoint.

This can happen when Gemini returns malformed JSON for complex queries. QWED automatically strips Markdown code fences from responses, but edge cases may still occur. Solution: Retry the request — the error is usually transient. If it persists, simplify your input or switch to a different provider temporarily.

SDK issues

Import error

ModuleNotFoundError: No module named 'qwed_sdk'

Solution:

pip install qwed
# or
pip install qwed-sdk

Async not working

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

Solution:

# 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'

Solution: Only use allowed operators:

Allowed	Not Allowed
AND, OR, NOT	CHECK, VALIDATE
GT, LT, EQ	GREATER, LESS
IMPLIES, IFF	IF, THEN
FORALL, EXISTS	ALL, ANY

# Wrong
"(CHECK_IF_VALID x)"

# Correct
"(GT x 0)"

Missing parentheses

SyntaxError: Missing closing ')'

Solution: Count your parentheses:

# 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

Possible causes:

Complex expressions with many variables
Large code files
Deep recursion in symbolic execution

Solutions:

# 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

Solution: Stream large results:

# 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

Code	Meaning	Solution
`E001`	Invalid expression	Check syntax
`E002`	Type mismatch	Check variable types
`E003`	Division by zero	Add guards
`E004`	Timeout	Simplify query
`E005`	Rate limit	Implement backoff
`E401`	Auth failed	Check API key
`E500`	Server error	Contact support

Getting help

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

Debug mode

Enable debug logging:

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")

Start here

Configure and understand

Releases

Help

Authentication errors

API key invalid

Rate limit exceeded

Verification failures

Math: floating-point precision

Logic: unsatisfiable constraints

Stats: Internal verification error

Code: timeout

CLI issues

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

Gemini provider issues

Missing `google-generativeai` package

Gemini API key not found

Gemini timeout errors

Gemini JSON parse errors

SDK issues

Import error

Async not working

DSL syntax errors

Unknown operator

Missing parentheses

Performance issues

Slow verification

High memory usage

Common error codes

Getting help

Debug mode

​Authentication errors

​API key invalid

​Rate limit exceeded

​Verification failures

​Math: floating-point precision

​Logic: unsatisfiable constraints

​Stats: Internal verification error

​Code: timeout

​CLI issues

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

​Gemini provider issues

​Missing google-generativeai package

​Gemini API key not found

​Gemini timeout errors

​Gemini JSON parse errors

​SDK issues

​Import error

​Async not working

​DSL syntax errors

​Unknown operator

​Missing parentheses

​Performance issues

​Slow verification

​High memory usage

​Common error codes

​Getting help

​Debug mode

Authentication errors

API key invalid

Rate limit exceeded

Verification failures

Math: floating-point precision

Logic: unsatisfiable constraints

Stats: Internal verification error

Code: timeout

CLI issues

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

Gemini provider issues

Missing `google-generativeai` package

Gemini API key not found

Gemini timeout errors

Gemini JSON parse errors

SDK issues

Import error

Async not working

DSL syntax errors

Unknown operator

Missing parentheses

Performance issues

Slow verification

High memory usage

Common error codes

Getting help

Debug mode