How to Fix "UCP namespace/origin mismatch"

What is a namespace/origin mismatch?

Every UCP manifest at /.well-known/ucp declares three critical identifier fields:

• namespace - the protocol namespace (almost always "ucp")
• origin - your store's canonical HTTPS URL (e.g. "https://yourstore.com")
• Capability spec_origin - the authority domain for each capability's specification

When these don't align, AI agents receive contradictory information about who controls the manifest and what the capabilities reference. The agent has no safe default - it must reject the profile rather than trust mismatched identifiers.

This is a rules-level validation failure. Your manifest looks fine structurally. It breaks at the business-logic layer where agents enforce trust boundaries.

How the mismatch breaks AI agent discovery

When an AI shopping agent reads your manifest, it checks:

Does namespace match the expected protocol?
Does origin match the domain this manifest was served from?
Does each capability's spec_origin trace to the correct namespace authority?

If any answer is "no," the agent stops. Your store might as well not have a manifest. The agent can't determine whether it's talking to your store, a compromised proxy, or a misconfigured endpoint.

The 3 types of namespace/origin mismatches

1. Bare origin mismatch (most common)

{
  "namespace": "ucp",
  "origin": "https://www.yourstore.com",
  ...
}

Manifest is served from https://yourstore.com/.well-known/ucp (no www). The origin declares www.yourstore.com but the agent fetched from yourstore.com. These are different origins. Every UCP capability endpoint must match the declared origin.

2. Capability spec_origin mismatch

{
  "namespace": "ucp",
  "origin": "https://yourstore.com",
  "capabilities": {
    "checkout": {
      "spec_origin": "https://not-yourstore.com/spec",
      "endpoint": "https://yourstore.com/api/ucp/checkout"
    }
  }
}

The checkout capability references a spec at not-yourstore.com. The agent must verify that spec_origin aligns with the declared namespace authority (typically ucp.dev). A spec hosted on an unrelated domain is untrusted.

3. Protocol namespace confusion

{
  "namespace": "ucp-custom",
  "origin": "https://yourstore.com",
  ...
}

The manifest uses a non-standard namespace. AI agents only recognize "ucp" (and increasingly "acp"). A custom namespace means the agent doesn't know how to interpret the capabilities and treats this as an unrecognized protocol.

How to fix namespace/origin mismatches

Fix 1: Align origin with the manifest URL

Your manifest at /.well-known/ucp must be served from the exact domain declared in origin. Checklist:

• Remove all trailing slashes from origin
• Use https:// (not http://)
• Match the canonical domain exactly (including subdomain decisions)
• If you redirect www to non-www (or vice versa), the origin must match the canonical URL, and the manifest must be served from that same canonical URL

Fix 2: Verify capability spec_origins

Each capability's spec_origin should reference the namespace authority for the protocol version you're targeting:

{
  "checkout": {
    "spec_origin": "https://ucp.dev",
    "endpoint": "https://yourstore.com/api/ucp/checkout"
  }
}

Fix 3: Use the standard namespace value

Almost every UCP profile should use "namespace": "ucp". Unless you're implementing a fork of the protocol that agents explicitly support, use the standard namespace.

Fix 4: Set up proper redirects (or don't)

Option A (recommended): Pick one canonical domain. Serve the manifest from that domain. Ensure capability endpoints use the same domain. Redirect the other domain at the application level, not just DNS. Option B: Serve identical manifests on both domains with matching origin values - error-prone and harder to maintain.

Fix 5: Ensure all capability endpoints use the same origin

All endpoints must use the exact same domain as origin, use https://, have no trailing slashes, and be served from a path that actually responds.

How to test your fix

A manifest that passes JSON schema validation can still fail at the rules level. You need a validator that tests at least level 2 (rules), and ideally level 4 (full simulation) - a rules-level mismatch is invisible to basic checkers. See the four levels of UCP validation.

Quick reference: namespace/origin requirements

Common related failures

• Missing signing_keys - agents can't verify your manifest even with correct identifiers
• Payment handlers empty or missing - agents see a valid profile but can't process transactions
• Broken Identity Linking - personalized commerce fails for recognized customers
• HTTP endpoints and capability endpoint 404s - network-level failures

Last updated: May 2026. UCP spec version 1.2 referenced. Namespace/origin alignment is a rules-level requirement - structural validation alone cannot verify it. UCPtools is an independent community tool - not affiliated with Google, Shopify, or the UCP consortium.