> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting guide

> Resolve common QWED verification issues including authentication errors, API key problems, and rate limits. Step-by-step debugging solutions included.

Common issues and how to resolve them.

***

## Authentication errors

### API key invalid

```
Error: 401 Unauthorized - Invalid API key
```

**Solution:**

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](https://cloud.qwedai.com)
4. Ensure no extra spaces or newlines

```python theme={null}
# 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

```python theme={null}
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

```python theme={null}
# 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:

```python theme={null}
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:

```python theme={null}
# 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:**

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
```

**Solution:**

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
```

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:

```bash theme={null}
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:

```bash theme={null}
cd ~/my-project
qwed init
```

***

### `qwed init` fails with "Server identity check failed"

```text theme={null}
  [x] Server identity check failed: server identity check failed: the running server holds a different jwt and lookup secret(s) than this project. ...
```

This error occurs during Step 3 of `qwed init`. Before bootstrapping an API key, the CLI asks the server on `--server-url` to prove it holds this project's `QWED_JWT_SECRET_KEY` and `QWED_API_KEY_LOOKUP_SECRET` through [`GET /health/identity`](/api/endpoints#get-health-identity). The check fails closed in any of these cases:

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

**Solution** — the first step depends on which reason the message reports:

* **"...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.

See [`qwed init`](/advanced/cli#qwed-init-onboarding-and-bootstrap).

***

## Gemini provider issues

### Missing `google-generativeai` package

```
ImportError: google-generativeai package required for Gemini integration.
```

**Solution:** Install the Gemini SDK alongside QWED:

```bash theme={null}
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`:

```bash theme={null}
export GOOGLE_API_KEY=your-google-api-key
```

Or run the setup wizard:

```bash theme={null}
qwed init
```

### Gemini timeout errors

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

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

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:**

```bash theme={null}
pip install qwed
# or
pip install qwed-sdk
```

### Async not working

```python theme={null}
# Wrong - missing await
result = client.verify("2+2=4")  # Returns coroutine, not result
```

**Solution:**

```python theme={null}
# 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 |

```python theme={null}
# Wrong
"(CHECK_IF_VALID x)"

# Correct
"(GT x 0)"
```

### Missing parentheses

```
SyntaxError: Missing closing ')'
```

**Solution:** Count your parentheses:

```python theme={null}
# 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:**

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

**Solutions:**

```python theme={null}
# 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:

```python theme={null}
# 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

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

***

## Debug mode

Enable debug logging:

```python theme={null}
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")
```


## Related topics

- [Monitoring](/integration/monitoring.md)
- [Prompt injection defense and QWED security hardening](/advanced/security-hardening.md)
- [QWED integration troubleshooting](/integration/troubleshooting.md)
- [QWED MCP troubleshooting](/mcp/troubleshooting.md)
- [QWED deployment guide](/advanced/deployment.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.