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

# QWED UCP troubleshooting

> Troubleshoot QWED UCP issues including Python version requirements, middleware setup, and checkout verification failures.

Common issues and solutions when using QWED-UCP.

***

## Installation issues

### "No module named 'qwed\_ucp'"

**Cause:** Package not installed correctly

**Solutions:**

1. **Check Python version** (requires 3.10+):
   ```bash theme={null}
   python --version
   ```

2. **Install in correct environment:**
   ```bash theme={null}
   pip install qwed-ucp
   # or with virtual env
   python -m venv venv
   source venv/bin/activate  # or venv\Scripts\activate on Windows
   pip install qwed-ucp
   ```

3. **Verify installation:**
   ```bash theme={null}
   pip show qwed-ucp
   python -c "from qwed_ucp import UCPVerifier; print('OK')"
   ```

***

### npm install fails for Express middleware

**Cause:** Node.js version incompatibility

**Solution:**

```bash theme={null}
# Requires Node.js 18+
node --version

# Install
npm install qwed-ucp-middleware
```

***

## Verification failures

### "Total mismatch: expected $X, got $Y"

**Cause:** Money Guard detected incorrect total calculation

**Debug:**

```python theme={null}
from qwed_ucp.guards import MoneyGuard
from decimal import Decimal

guard = MoneyGuard()
result = guard.verify(checkout)

if not result.verified:
    print(f"Expected total: {result.expected}")
    print(f"Actual total: {result.actual}")
    print(f"Difference: {result.difference}")
```

**Common causes:**

* Discount not subtracted
* Tax calculated on wrong base
* Rounding differences

**Fix:** Use `Decimal` for monetary calculations:

```python theme={null}
from decimal import Decimal, ROUND_HALF_UP

subtotal = Decimal("100.00")
discount = subtotal * Decimal("0.10")  # 10%
tax = (subtotal - discount) * Decimal("0.0825")
total = (subtotal - discount + tax).quantize(Decimal("0.01"), ROUND_HALF_UP)
```

***

### "Line item mismatch: qty × price ≠ line\_total"

**Cause:** Line Items Guard detected math error

**Debug:**

```python theme={null}
for item in checkout["line_items"]:
    expected = item["quantity"] * item["item"]["price"]
    print(f"Item: {item['id']}")
    print(f"  {item['quantity']} × ${item['item']['price']} = ${expected}")
```

**Common causes:**

* Floating-point precision issues
* Wrong quantity multiplied
* Missing items in calculation

***

### "Invalid currency: JPY amounts cannot have decimals"

**Cause:** Currency Guard detected invalid format

**Zero-decimal currencies:**

* JPY (Japanese Yen)
* KRW (Korean Won)
* VND (Vietnamese Dong)

**Fix:**

```python theme={null}
# Wrong
{"currency": "JPY", "amount": 1000.50}

# Correct
{"currency": "JPY", "amount": 1000}
```

***

### "Invalid state transition"

**Cause:** State Guard detected invalid checkout flow

**Valid transitions:**

```
incomplete → ready_for_complete → completed
                               → failed → cancelled
```

**Invalid examples:**

* `completed → incomplete` (can't go back)
* `cancelled → ready_for_complete` (can't resurrect)

**Fix:** Follow the state machine flow properly.

***

## Middleware issues

### FastAPI middleware not intercepting requests

**Check route configuration:**

```python theme={null}
# Make sure middleware is added BEFORE routes
app = FastAPI()
app.add_middleware(QWEDUCPMiddleware)  # First

@app.post("/checkout")  # Then routes
async def checkout(): ...
```

**Check verify\_paths:**

```python theme={null}
app.add_middleware(
    QWEDUCPMiddleware,
    verify_paths=["/checkout", "/api/v1/checkout"]  # Must match your routes
)
```

***

### Express middleware returns 500 instead of 422

**Check error handling:**

```javascript theme={null}
app.use('/checkout', createQWEDUCPMiddleware({
    onFailure: (error, req, res) => {
        // Make sure this doesn't throw
        res.status(422).json({
            error: error.message
        });
    }
}));
```

***

### CORS issues with middleware

**Solution for FastAPI:**

```python theme={null}
from fastapi.middleware.cors import CORSMiddleware

# Add CORS BEFORE QWED-UCP
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)
app.add_middleware(QWEDUCPMiddleware)
```

***

## Performance issues

### Verification is slow

**Optimize with caching:**

```python theme={null}
from functools import lru_cache

@lru_cache(maxsize=1000)
def verify_cached(checkout_hash: str, checkout_json: str):
    return verifier.verify_checkout(json.loads(checkout_json))
```

**Skip unchanged checkouts:**

```python theme={null}
# Calculate hash first
checkout_hash = hash(frozenset(checkout.items()))
if checkout_hash in verified_cache:
    return verified_cache[checkout_hash]
```

***

## Common errors reference

| Error message               | Guard     | Cause                   | Fix                  |
| --------------------------- | --------- | ----------------------- | -------------------- |
| "Total mismatch"            | Money     | Wrong total calculation | Recalculate total    |
| "Line item mismatch"        | LineItems | qty × price error       | Check each line      |
| "Invalid currency"          | Currency  | Bad format              | Check ISO 4217       |
| "Invalid transition"        | State     | Wrong state flow        | Follow state machine |
| "Schema validation failed"  | Schema    | Missing fields          | Check UCP schema     |
| "Discount exceeds subtotal" | Discount  | Over 100% off           | Cap discount         |

***

## Getting help

1. **GitHub Issues:** [github.com/QWED-AI/qwed-ucp/issues](https://github.com/QWED-AI/qwed-ucp/issues)
2. **Documentation:** [docs.qwedai.com/ucp](https://docs.qwedai.com/docs/ucp/overview)
3. **UCP Protocol:** [developers.google.com/commerce/ucp](https://developers.google.com/commerce/ucp)