Troubleshooting Guides

Check DNS resolution

dig your-store.com A
dig your-store.com AAAA
# Ensure the domain resolves to your server's IP

Check HTTPS

UCP requires HTTPS. Verify your SSL certificate is valid:

curl -I https://your-store.com/.well-known/ucp
# Expected: 200 OK
# Not: 301 redirect to HTTP, SSL error, or timeout

Check content type

curl -I https://your-store.com/.well-known/ucp | grep Content-Type
# Expected: application/json

Check CORS headers

curl -I -X OPTIONS https://your-store.com/.well-known/ucp
# Must include:
# Access-Control-Allow-Origin: *
# Access-Control-Allow-Methods: GET
# Access-Control-Allow-Headers: Content-Type, UCP-Agent

Validate JSON structure

curl -s https://your-store.com/.well-known/ucp | jq .
# If jq fails, your JSON is malformed

Check required fields

curl -s https://your-store.com/.well-known/ucp | \
  jq '{version: .ucp.version, services: (.ucp.services | keys), capabilities: (.ucp.capabilities | keys)}'
# Must have: version, at least one service, at least one capability

Check protocol version match

# Merchant's version
curl -s https://merchant.com/.well-known/ucp | jq .ucp.version

# Agent's version (check your client config)
# If they don't match, check supported_versions:
curl -s https://merchant.com/.well-known/ucp | jq .ucp.supported_versions

Check capability versions

Each capability is an array that can contain multiple versions. Ensure the agent and merchant have at least one version in common:

curl -s https://merchant.com/.well-known/ucp | \
  jq '.ucp.capabilities["dev.ucp.shopping.checkout"][] | .version'

Check namespace binding

Spec URLs must match namespace authority. If they do not, platforms will reject the capability:

curl -s https://merchant.com/.well-known/ucp | \
  jq '.ucp.capabilities["dev.ucp.shopping.checkout"][0].spec'
# Must start with https://ucp.dev/ for dev.ucp.* capabilities

Check extension requires

If you are using extensions, their requires constraints must be satisfied:

# Fetch the extension schema and check requires
curl -s https://ucp.dev/.../discount.json | jq .requires
# Ensure your protocol version and capability versions meet the min/max

Check checkout status

GET https://your-store.com/api/ucp/checkout-sessions/{id}
# Check the status field:
# incomplete - missing required fields
# ready_for_complete - ready for payment
# requires_escalation - needs human input
# expired - timed out

If status is "incomplete"

You are missing required fields. Check:

• buyer.email - required
• buyer.first_name and buyer.last_name - required
• fulfillment.methods - at least one method required
• fulfillment.methods[0].selected_destination_id - must be set

If status is "requires_escalation"

This is normal, not an error. Present the continue_url to the buyer:

// In your agent's response to the user:
"I need you to verify your payment in your browser.
Please visit: {continue_url}
Once you're done, I'll check your order status."

If payment_handler_error

The payment processor returned an error. Check:

• Is the payment instrument token valid and not expired?
• Is the AP2 mandate correctly signed?
• Does the currency match?
• Check your payment handler's dashboard for the underlying error

Check webhook subscription

Ensure your agent has subscribed to order lifecycle events. The subscription endpoint varies by implementation - check the merchant's OpenAPI spec.

Check endpoint accessibility

# Can the merchant reach your webhook URL?
curl -X POST https://your-agent.com/webhooks/ucp \
  -H "Content-Type: application/json" \
  -d '{"test": true}'
# Should return 200 OK

Check signature validation

Webhooks may be signed. If your signature validation fails, you might be silently dropping events:

// Verify webhook signature (implementation varies)
const signature = req.headers['ucp-signature'];
const payload = JSON.stringify(req.body);
if (!verifySignature(payload, signature, publicKey)) {
  return res.status(401).send('Invalid signature');
}

Use get_order as fallback

If webhooks are unreliable, agents can fetch fresh order state on demand:

GET https://merchant.com/api/ucp/orders/{order_id}
# Use this when a webhook is missed or when the buyer asks "where's my order?"

Check schema URL accessibility

# For each capability, check the schema URL
curl -I https://ucp.dev/2026-04-08/schemas/shopping/checkout.json
# Must return 200 OK

Check $defs keys match extends

For extensions, each parent in extends must have a matching $defs key:

// If extends: ["dev.ucp.shopping.checkout", "dev.ucp.shopping.cart"]
// Then $defs MUST have:
{
  "$defs": {
    "dev.ucp.shopping.checkout": { ... },
    "dev.ucp.shopping.cart": { ... }
  }
}

Check requires constraints

If an extension has requires, ensure the negotiated versions satisfy it:

// Extension requires:
"requires": {
  "protocol": { "min": "2026-04-08" },
  "capabilities": {
    "dev.ucp.shopping.checkout": { "min": "2026-04-08" }
  }
}

// Your negotiated versions must be >= min (and <= max if specified)

Add CORS headers

# nginx
location /api/ucp/ {
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
    add_header Access-Control-Allow-Headers "Content-Type, UCP-Agent";
    
    if ($request_method = OPTIONS) {
        return 204;
    }
    
    proxy_pass http://your_backend;
}

Include UCP-Agent in allowed headers

The UCP-Agent header is required for checkout operations. If it is not in Access-Control-Allow-Headers, preflight will fail.

Handle OPTIONS preflight

Browser-based agents send OPTIONS requests before actual requests. Your server must respond with 204 No Content and the CORS headers.