QWED UCP troubleshooting

Common issues and solutions when using QWED-UCP.

Installation issues

”No module named ‘qwed_ucp’”

Cause: Package not installed correctly Solutions:

Check Python version (requires 3.10+):
python --version

Install in correct environment:

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

Verify installation:

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:

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

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:

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:

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:

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

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

app.add_middleware(
    QWEDUCPMiddleware,
    verify_paths=["/checkout", "/api/v1/checkout"]  # Must match your routes
)

Express middleware returns `500 INTERNAL_VERIFICATION_ERROR`

Cause: A guard raised an unexpected exception mid-verification. The Express middleware fails closed on this path — it does not call next(), and the client receives:

{
  "error": "QWED-UCP Verification Failed",
  "message": "Internal verification error: verification could not be completed",
  "code": "INTERNAL_VERIFICATION_ERROR"
}

The response is intentional: an unverified request must not settle. The underlying exception is written to stderr via console.error('QWED-UCP Middleware Error:', error) — check your server logs for the stack trace. Fix:

Reproduce the request locally and inspect the logged exception.
If the payload has unexpected shape (missing currency, non-numeric amounts, etc.), tighten your upstream validation or add the field before the middleware runs.
If a specific guard is crashing, file an issue with the offending payload — do not “recover” by catching the 500 and forwarding the request.

CORS issues with middleware

Solution for FastAPI:

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:

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:

# 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
”Empty request body”	FastAPI Middleware	No body on protected path	Send a JSON object body
”Malformed request body: expected JSON”	FastAPI Middleware	Non-JSON or non-UTF-8 body	Use `Content-Type: application/json`
”Invalid request body: expected JSON object”	FastAPI Middleware	Top-level array/primitive	Wrap payload in an object
”Empty or non-JSON request body: cannot verify unparseable payload”	Express Middleware	Empty, malformed, or non-object body	Use `Content-Type: application/json` with `express.json()` registered first
”Internal verification error: verification could not be completed”	Express Middleware	Guard raised an unexpected exception (returns `500 INTERNAL_VERIFICATION_ERROR`, fail-closed)	Check server logs for the underlying stack trace

`UNPARSEABLE_REQUEST` (422) from middleware

Cause: The FastAPI or Express middleware received a request on a protected path (/checkout-sessions, /checkout, /cart, /payment) that it could not parse as a JSON object, so it failed closed before running guards. Common triggers:

Empty body on a POST/PUT/PATCH
Form-encoded, XML, or binary body instead of JSON
Malformed JSON (trailing comma, unquoted key, truncated payload)
Top-level JSON array, number, string, null, or boolean

Fix: Send a JSON object with Content-Type: application/json:

curl -X POST http://localhost:8182/checkout-sessions \
  -H "Content-Type: application/json" \
  -d '{"currency":"USD","line_items":[]}'

If your endpoint is not a checkout route, either rename it or narrow verify_paths so the middleware skips it:

app.add_middleware(QWEDUCPMiddleware, verify_paths=["/checkout-sessions"])

Getting help

GitHub Issues: github.com/QWED-AI/qwed-ucp/issues
Documentation: docs.qwedai.com/ucp
UCP Protocol: developers.google.com/commerce/ucp

MCP Server

Open Responses

UCP (Commerce)

Installation issues

”No module named ‘qwed_ucp’”

npm install fails for Express middleware

Verification failures

”Total mismatch: expected $X, got$ Y”

“Line item mismatch: qty × price ≠ line_total”

”Invalid currency: JPY amounts cannot have decimals”

“Invalid state transition”

Middleware issues

FastAPI middleware not intercepting requests

Express middleware returns `500 INTERNAL_VERIFICATION_ERROR`

CORS issues with middleware

Performance issues

Verification is slow

Common errors reference

`UNPARSEABLE_REQUEST` (422) from middleware

Getting help

​Installation issues

​”No module named ‘qwed_ucp’”

​npm install fails for Express middleware

​Verification failures

​”Total mismatch: expected X,gotX, got X,gotY”

​“Line item mismatch: qty × price ≠ line_total”

​”Invalid currency: JPY amounts cannot have decimals”

​“Invalid state transition”

​Middleware issues

​FastAPI middleware not intercepting requests

​Express middleware returns 500 INTERNAL_VERIFICATION_ERROR

​CORS issues with middleware

​Performance issues

​Verification is slow

​Common errors reference

​UNPARSEABLE_REQUEST (422) from middleware

​Getting help

Installation issues

”No module named ‘qwed_ucp’”

npm install fails for Express middleware

Verification failures

”Total mismatch: expected $X, got$ Y”

“Line item mismatch: qty × price ≠ line_total”

”Invalid currency: JPY amounts cannot have decimals”

“Invalid state transition”

Middleware issues

FastAPI middleware not intercepting requests

Express middleware returns `500 INTERNAL_VERIFICATION_ERROR`

CORS issues with middleware

Performance issues

Verification is slow

Common errors reference

`UNPARSEABLE_REQUEST` (422) from middleware

Getting help