8. Troubleshooting & FAQ

My profile is empty / capabilities are missing

1. Confirm UCP active is on in the General card.
2. Confirm at least one capability toggle is on in the Capabilities card.
3. Click Save.
4. Wait up to 60 s for the profile cache to refresh, or curl your profile URL directly to bypass the browser cache.
5. If the profile is still empty, check that the UCP_SERVER feature flag is on at the application level. Without it, all UCP routes return 404.

I see "404 Not Found" at /.well-known/ucp

The UCP_SERVER feature flag is most likely off. Set UCP_SERVER=1 in .env and restart the application, or run bin/console feature:enable UCP_SERVER.

My webhook arrives at the platform but is rejected

Open the simulator's Webhooks: open listener scenario and have your shop POST the next webhook to its URL. The simulator surfaces the verification failure reason:

• key not found in JWKS — the kid in the signature header does not match any public key in your published profile. Either your shop is signing with a key that is no longer in signing_keys[], or the platform cached an old profile. Force-refresh the platform's cache, or rotate the key fresh.
• content-digest mismatch — the body the platform received does not match the body your shop hashed. Most often caused by a reverse proxy modifying the response body (gzipping, JSON re-serializing, charset rewriting). Make the proxy a transparent passthrough for /.well-known/ucp and webhook payloads.
• signature verification failed — the cryptographic signature itself is invalid. Almost always points to a clock-skew issue beyond the spec's 60 s tolerance, or a transcoding issue in transit.

I want to turn off a single capability without taking the whole channel offline

Open the detail page, toggle off the capability you don't want, click Save. Within a minute the published profile no longer advertises it. Agents that already negotiated based on the old profile may keep using the capability until they refresh; force them to refresh by rotating your signing key if it's urgent.

Can I expose different capabilities on different domains of the same Sales Channel?

The current release publishes one profile per Sales Channel. Per-domain overrides (different capabilities per language/region) are on the roadmap for the next minor release.

Does enabling UCP make my shop's data public?

No more than your storefront already is. UCP does not bypass any permission check:

• Catalog data is filtered through the Sales Channel context just like the existing storefront.
• Cart and checkout operate against a guest session unless an identity-linking token is presented.
• Order-history read access requires the buyer to have linked their account via OAuth and granted the dev.ucp.shopping.order:read scope explicitly.

Where do I report bugs?

Open an issue on the shopware/shopware repo with the ucp label. Include the output of the simulator's HTTP debug pane for the failing call — that alone usually pinpoints the issue.

← Back to end-user index · See also developer docs