An assistant says it can't reach your store: what to check, by symptom Free & Pro

The report usually arrives second-hand: a customer says their assistant "couldn’t connect to your shop", or "says it isn’t allowed". Assistants word these differently, so this guide starts from what the customer was told, names the usual cause, and says how to confirm and fix it. Start with Tools → Site Health in every case; it catches the first five below. Then come here for the rest.

"It couldn’t find your store" or "that store doesn’t support assistants"

The assistant could not fetch /.well-known/poppy.json, or got something other than JSON.

• Confirm: open https://your-store/.well-known/poppy.json in a private window. JSON naming your store means discovery is fine and the problem is further on. An HTML page, a redirect to your home page, a 404 or a challenge page means it isn’t.
• Causes, in order of likelihood: a page cache or CDN serving a cached page for that path; a security plugin or bot-fighting rule answering before WordPress; pretty permalinks off; WordPress installed in a sub-folder; the plugin not active (it stays inactive, with a dashboard notice, if WordPress, WooCommerce or PHP is too old).
• Fix: exclude /.well-known/ and /agent-adapt/ from caching and bot rules, set permalinks to anything but Plain, forward the path if WordPress lives in a folder. See Caches, CDNs and security plugins and Site Health checks.

The customer gave the assistant the wrong domain more often than you would think. Discovery is at the root of the domain customers use; shop.example.com and example.com are different stores to an assistant.

"The store refused to start a session" or "authentication failed"

The assistant reached discovery but the token request failed.

• Confirm: run requests 2 and 5 in Check that your store answers agents. The OAuth metadata should be JSON; an empty POST to the token endpoint should get a JSON invalid_request, not HTML or a 404.
• Causes: /agent-adapt/ intercepted by a cache or firewall; the Authorization header stripped before PHP (Site Health names this one); the agent is blocked on your Agents screen; with Pro, the allowlist is on and this agent isn’t ticked; the agent’s own published documents are unreachable or wrong (its jwks_uri on another domain, a key the store can’t fetch), which is the agent’s problem, not yours.
• Fix: the exclusions above; the one-line .htaccess rule from Site Health; unblock or tick the agent under WooCommerce → Agents.

If the assistant is one you have never seen on the Agents screen, it never got as far as a verified visit. If it is there and marked Blocked, that is your answer.

"Too many requests" or "try again later"

The agent went over a rate limit and was told to wait, which well-behaved agents do on their own.

• Confirm: nothing to fix on your side unless it keeps happening. The limits are 300 API calls a minute per visit, 120 token requests a minute per address, and tighter limits on agents the store has never seen. See Limits, lifetimes and developer filters.
• Causes: an agent polling your store far more often than a person would; many agents behind one address.
• Fix: usually none. A developer can raise a limit with the agentadapt_rate_limit filter if a legitimate agent needs more.

"I need you to sign in first" when the customer already did

The agent has a signed-out visit and is asking for something that needs the account, or its earlier approval has ended.

• Causes: the approval expired (90 days); the customer disconnected the agent from My Account → Connected agents; the customer changed their password or email, which ends every approval; the customer’s account was promoted to a role that can’t be connected; you blocked and later unblocked the agent (approvals survive that, but the agent may need to renew its visit).
• Fix: the customer connects the agent again. If it keeps happening within days, check whether something is changing the customer’s password or email programmatically, or a security plugin is forcing resets.

"That action isn’t allowed" or "the store doesn’t permit this"

The agent asked for something your store refused on purpose.

• Causes: the customer approved only View and the agent tried to make a change; with Pro, you have switched that action off, capped the agent at view-only, or the order isn’t in a state the action allows (paid cancellation needs Processing, returns need Completed within your return window); the agent doesn’t declare support for operations and asked for a paid cancellation, return or address change; a staff account was used.
• Confirm: with Pro, Agent insights → Where agents get stuck lists refusals by reason and action. Without Pro, ask the customer what the assistant was trying to do.
• Fix: if you want the action allowed, change your policy or ask the customer to grant the permission. If not, nothing is wrong.

"It worked, then the checkout link didn’t"

The customer opened a checkout link late, or twice.

• Causes: a link works once and lasts 30 minutes. The customer sees This checkout link has expired or was already used. Ask your assistant for a new one. The cart is still with the agent’s visit.
• Fix: the assistant asks for a new link.

"Everything works, but the cart was empty at checkout"

The link was opened in a different browser or device from the one the customer was signed in on, or a security plugin cleared the session on the way.

• Causes: the checkout link adds the agent’s items to the cart of whichever browser opens it. Opening it in an in-app browser and then switching to a normal browser leaves the items in the first. A plugin that wipes WooCommerce sessions, or very aggressive cache rules on the cart and checkout pages, can lose them.
• Fix: open the link in the browser the customer will pay in. Make sure your cache skips cart and checkout for visitors with items in their cart, as WooCommerce expects.

It used to work, and nothing changed on your side

• The protocol is a draft and may have changed. If the assistant’s maker moved to a newer draft before we did, or the other way round, the two can disagree. Check the changelog for the draft we follow.
• The agent’s own documents changed. An agent that rotated keys badly, or moved its client_id, is a new agent to your store with no approvals. Not yours to fix, but worth telling the customer.
• Your host changed something. A new CDN setting, a security plugin update with bot-fighting on by default, or an .htaccess regenerated without the Authorization line. Site Health will say.

When to write to us

If Site Health is green, the five curl checks pass, the agent isn’t blocked, and a customer’s assistant still fails, email [email protected] with the agent’s name and address from the Agents screen, what the customer was told, and roughly when. Don’t send tokens, logs with Authorization headers, or customer details.

Common questions

Can I see the error the agent got?

The free plugin records events but not the text of each error. With Pro, Agent insights → Where agents get stuck shows refusals by reason. For transport-level failures (caches, firewalls) the agent never reached the plugin, so nothing is recorded; the curl checks reproduce what it saw.

Is there a way to test as an agent myself?

Not without an agent’s keys. The curl checks show that each endpoint answers correctly; a full visit needs a signed request, which the plugin’s own test suite performs on every release.

Could the customer’s assistant simply not support the protocol?

Yes, and in late 2026 that is common. An assistant that doesn’t implement the Personal Agent Protocol will browse your site like a visitor and may say it "can’t log in". Nothing on your store changes that; it is for the assistant’s maker to add.

Does blocking an agent tell the customer why?

The agent receives a standard refusal with no reason. What the customer sees depends on their assistant. If you block an agent that customers rely on, expect questions.