How to Fix "UCP namespace/origin mismatch" - Complete Guide (2026)

Your UCP manifest is valid JSON. All required fields are present. But AI agents still reject it because your namespace and origin don't agree. Here's exactly why this breaks agent discovery - and how to fix it in 10 minutes.

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

An AI shopping agent encounters your store through one of these paths:

1. User asks "find me a red wool sweater" and Google AI Mode queries its merchant index
2. ChatGPT browses for products matching a user's request
3. An autonomous agent follows a product link and reads your /.well-known/ucp

In every case, the agent reads your manifest and 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 problem: The origin field declares www.yourstore.com but the agent fetched the manifest from yourstore.com. These are different origins per the same-origin policy. 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 problem: The checkout capability references a spec at not-yourstore.com. The agent must verify that the capability's spec_origin aligns with the declared namespace authority (typically ucp.dev for the UCP namespace). A spec hosted on an unrelated domain is untrusted.

3. Protocol namespace confusion

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

The problem: The manifest uses a non-standard namespace. AI agents only recognize "ucp" (and increasingly "acp" for ACP-compatible profiles). A custom namespace means the agent doesn't know how to interpret the capabilities, even if the fields look correct. It will treat 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:

If your store is at yourstore.com:

{
  "origin": "https://yourstore.com"
}

If your store uses www:

{
  "origin": "https://www.yourstore.com"
}

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"
  }
}

For UCP namespace, valid spec_origins include https://ucp.dev (the canonical UCP specification site). Check the latest UCP spec for the current authority domains.

Fix 3: Use 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. Custom namespaces are treated as unrecognized protocols.

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

If your store redirects between www and non-www:

Option A (recommended): Pick one canonical domain. Serve the manifest from that domain. Ensure capability endpoints use that 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. This is error-prone and harder to maintain. Option A is simpler.

Fix 5: Ensure all capability endpoints use the same origin

Your capability endpoints must match the declared origin:

{
  "origin": "https://yourstore.com",
  "capabilities": {
    "checkout": {
      "endpoint": "https://yourstore.com/api/ucp/checkout"
    },
    "payment": {
      "endpoint": "https://yourstore.com/api/ucp/payment"
    }
  }
}

All endpoints must:

• Use the exact same domain as origin
• Use https://
• Have no trailing slashes
• Be served from a path that actually responds

How to test your fix

Don't rely on structural-only validators. A manifest that passes JSON schema validation can still fail at the rules level:

1. Structural check: Is the JSON valid? Are namespace and origin present?
2. Rules check: Do origin, namespace, and spec_origins align with spec requirements?
3. Network check: Can agents fetch the manifest over HTTPS from the declared origin?
4. SDK/Simulation: Can an AI agent actually parse the identifiers and proceed to interact with your capabilities?

A rules-level mismatch is invisible to basic checkers. You need a validator that tests at least level 2 (rules), and ideally level 4 (full simulation).

Run a free 4-level validation at ucptools.dev to catch namespace/origin mismatches plus all other failure classes in one scan.

Common related failures

If you're fixing namespace/origin mismatches, also check:

• 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
• HTTP endpoints - all capability endpoints require HTTPS; HTTP endpoints cause network-level failures
• Capability endpoint 404s - the endpoint path exists in the manifest but the server returns 404

Quick reference: namespace/origin requirements

Last updated: May 2026. UCP spec version 1.2 referenced. Namespace/origin alignment is a rules-level requirement - structural validation alone cannot verify it.