We've been monitoring 4,500+ UCP endpoints every 24 hours since January. The data gives us something no theoretical guide can: a ranked list of what actually breaks, how often, and what fixes it.

If your UCP endpoint isn't working, you're in the right place. This is the definitive UCP troubleshooting guide — not a spec reference, It's a field guide to the errors you'll hit in production, ordered by how frequently we see them. Each error includes the exact fix, the tools to debug it, and links to the platform-specific guide for your stack.

#UCP manifest not found (HTTP 404)

Error code: UCP_MANIFEST_NOT_FOUND How common: The single most common failure. Hundreds of stores in our crawler return 404 at /.well-known/ucp.

This means the store hasn't published a UCP manifest at all. No file exists at the well-known path. The fix depends on your platform:

• Shopify — UCP is handled at the platform level. If your Shopify store isn't showing a manifest, check that you're on a plan that includes UCP support. Most Shopify stores get it automatically.
• WooCommerce — you need to manually publish the manifest. See our WooCommerce UCP guide for plugin options and manual configuration.
• BigCommerce — similar to WooCommerce, manual setup required. Our BigCommerce guide covers the API-first approach.
• Custom stacks — serve a JSON file at /.well-known/ucp from your web server. The /.well-known/ucp developer guide has copy-paste examples for Nginx, Cloudflare Workers, Node, and static hosts.

Quick check: Run your domain through UCPChecker — it'll tell you instantly whether the manifest is reachable.

#Response is not valid JSON

Error code: UCP_RESPONSE_NOT_JSON How common: The second most common hard failure. The endpoint exists but returns HTML, XML, or plain text instead of JSON.

This usually happens when:

1. The Content-Type header is wrong. The manifest must be served as application/json. Some web servers default to text/html for files without an extension.
2. A WAF or CDN is intercepting the request and returning an error page, captcha, or redirect page instead of the JSON file.
3. The file is malformed JSON — a trailing comma, an unescaped character, or a BOM (byte order mark) at the start of the file.

Fix: Check your Content-Type header with curl -I https://yourstore.com/.well-known/ucp. It should return application/json. If you see text/html, configure your web server to set the correct MIME type. See the six most common mistakes in our developer guide.

#Missing required field: ucp.services

Error code: UCP_MISSING_SERVICES How common: Appears in stores that publish a partial manifest — typically a skeleton file that has the version but no service declarations.

The services field is where you declare which transports (MCP, REST, A2A, Embedded) agents can use to connect to your store and which endpoints to call. Without it, an agent knows you exist but has no way to interact with you.

Fix: Add at least one service entry with a transport, endpoint, and version. The minimal valid manifest example shows exactly what's required.

#Missing required field: ucp.payment_handlers

Error code: UCP_MISSING_PAYMENT_CONFIG How common: Common on early-stage implementations that handle products but haven't configured payment declarations.

Note the distinction: payment_handlers can be an empty array [] (valid — means the store uses checkout-link redirects instead of tokenized payments), but the key itself must be present. If it's absent entirely, the validator fails.

Fix: Add "payment_handlers": {} to your manifest. If you use WooCommerce checkout-link redirects, an empty object or array is valid. If you tokenize payments, declare your handlers — see the payment handlers directory for the namespace format.

#signing_keys in the wrong location

Error code: UCP_MISSING_SIGNING_KEYS How common: The most frequent warning on verified stores. 10+ stores in our latest crawl show this.

In v2026-04-08, signing_keys moved from ucp.signing_keys (nested inside the ucp object) to the document root (alongside ucp). Stores that haven't migrated still nest it under ucp, which triggers a warning.

Fix: Move signing_keys to the root level:

{
  "ucp": { "version": "2026-04-08", ... },
  "signing_keys": []
}

See the v2026-04-08 spec update for the full list of breaking changes.

#Variant mismatches at checkout

Where it happens: Not a manifest validation error — this is a runtime failure observed in UCP Playground sessions. How common: The #1 reason agent sessions fail to complete a purchase, based on our agent testing data.

This UCP variant mismatch error is the most frustrating because it's invisible at the schema level. The agent selects a product, identifies a variant (size, colour, configuration), and submits a cart or checkout request with a variant ID that doesn't match what the endpoint expects. The session errors out or adds the wrong item — a UCP checkout error that no amount of schema validation can catch.

This isn't an agent problem — it's a data clarity problem. Stores with clean, unambiguous variant structures see dramatically higher agent completion rates.

Fix: Audit your variant data. Every variant needs:

• A stable identifier that doesn't change between API responses
• A clear human-readable name
• Consistent representation across discovery and checkout endpoints

Run your store through UCP Playground with multiple models to see exactly where variant resolution breaks.

#Stale spec version

Warning code: UCP_OUTDATED_SPEC How common: 26 stores in the directory are still on spec versions older than v2026-04-08.

When Shopify migrated their fleet in four days, 99.4% of stores upgraded automatically. The remaining 26 are almost entirely non-Shopify stores that need to update manually.

Fix: Update the version field in your manifest to "2026-04-08" and apply the spec changes (signing_keys relocation, business profile distinction). Then validate to confirm.

#robots.txt blocking /.well-known/ucp

Error code: UCP_ROBOTS_BLOCKED How common: Rare but impactful. A handful of stores explicitly disallow /.well-known/ucp or all of /.well-known/* in their robots.txt.

AI agents that respect robots.txt will not fetch the manifest, even if it exists and is valid. The store is effectively invisible to these agents.

Fix: Add an explicit allow rule for the UCP endpoint in your robots.txt:

User-agent: *
Allow: /.well-known/ucp

#How to find your errors

Three ways to diagnose (plus two more for deeper analysis):

1. UCPChecker — paste your domain, get the full diagnostic in seconds. Shows every error and warning with the specific code and a plain-English explanation.
2. UCP Playground — run a real AI agent session against your store and watch where it breaks. Catches runtime failures (variant mismatches, cart errors, checkout timeouts) that manifest validation can't.
3. UCP Alerts — set up monitoring and get emailed when your store's status changes. Catches regressions before agents do.

For deeper investigation, compare your store side-by-side with a competitor to see where your implementation differs, or browse the platform adoption page to see how stores on your platform typically perform. Check the capability registry to verify you're declaring the right capability names, and the transport list to confirm your transport declaration is valid.

Once you've fixed the validation errors, the next step is understanding the full UCP requirements checklist to make sure nothing else is missing. And if you're not sure whether your store passes at all, start with Is My Store UCP Ready? — it walks through the check in 60 seconds.

For the broader context on what separates verified stores from truly agent-ready ones, see the Agentic Commerce Optimization guide. And to understand how your store appears in the ecosystem, check your listing on UCP Registry.

The errors above account for the vast majority of failures we see across 4,500+ monitored endpoints. Fix them in order — manifest existence first, then JSON validity, then required fields, then runtime issues — and you'll be ahead of most of the ecosystem.

Check your store for errors now at UCPChecker.com. Platform-specific fixes: Shopify · WooCommerce · BigCommerce · Magento