Technical troubleshooting

First step in every case: ask Claude to run ps_get_shop_info and ps_check_shop_health. Together they report versions, connector type (daily or service), read-only mode, licence state, enabled blocks and groups, customer data level, missing employee permissions and modules hooked into saves. The connection log in the module panel shows each call with IP, status and time.

Connection

The connector doesn't connect from Claude.ai.

Check in this order:

1. The address is https://your-shop.com/module/tellmyshop/mcp with the full token. The endpoint refuses plain HTTP (403).
2. The connector is switched on in the Start card. Off returns 503 "connector disabled"; it is off after install.
3. "Test the connection again" in the module works (test token, valid 2 minutes). The test doesn't detect country or IP blocks at a CDN; the first real call from Claude in the connection log does.
4. Nothing in front of the shop blocks POST to /module/tellmyshop/mcp: basic auth, maintenance page, WAF, Cloudflare Bot Fight Mode or managed challenges. Add a skip rule for that path only.
5. The IP allowlist, if set, includes Anthropic's range (160.79.104.0/21) and the IPs of machines using Claude Code.
6. Shop behind Cloudflare or another proxy: turn on "Shop behind a proxy / Cloudflare" and list the proxy ranges as trusted proxies, otherwise the allowlist sees the proxy's IP.

403 Forbidden.

Likely causes:

• Origin. A request with an Origin header is accepted only from https://claude.ai, https://claude.com, https://chatgpt.com or https://chat.openai.com. Requests without Origin pass. A browser-based test tool with another Origin is refused.
• IP allowlist. The IP is not on the list.
• Service connector. The service token works only from IPs on the service allowlist, only while one of blocks 3–5 is on (service mode also expires) and only with an active licence.

429 Too many failed attempts.

20 failed authentications from one IP within 10 minutes lock that IP until the window passes; the owner gets an alert. Typical cause: an old token still configured in Claude or in a monitoring script. Fix the token, then wait 10 minutes.

401 after a token was regenerated.

A new token revokes the old one immediately. Update the connector URL in Claude, or the Authorization: Bearer header in Claude Code / Claude Desktop config. The service token also expires after 30 days by default (SERVICE_TOKEN_TTL, 7–90).

Claude Code or Claude Desktop (local) can't connect.

Use --header "Authorization: Bearer <token>" instead of a URL token. The endpoint needs HTTPS even locally (mkcert). Requests without an Origin header pass. If an IP allowlist is set, add the machine's public IP.

Protocol version error.

Supported: 2026-07-28, and 2025-11-25, 2025-06-18, 2025-03-26. An unsupported version returns 400 with the supported list.

Tools missing

Only read tools are visible.

Either READ_ONLY is on (default after install), or the licence is not active (the paid package then behaves like Audit), or this is the free Audit package, which has no write tools. ps_get_shop_info says which.

Theme, module or service tools are missing.

Blocks 3–5 exist only on the service connector. Check: service token generated and not expired, service connector added in Claude as a separate connector, request from an IP on the service allowlist, the block switched on (block 5: timer still running), paid package with an active licence. Through the daily connector they never appear.

ps_list_file_backups / ps_restore_file_backup are missing.

They belong to the shared files group, visible on the service connector only while any of blocks 3–5 is on. Restoring a backup of a module file needs block 4; of a shop file, block 5.

Customer service tool is missing or refuses.

ps_customer_service is in the support group (off by default). It refuses with a message while customer data level is off; set pseudo or full in the Customer data (GDPR) card.

Blog tools are missing.

The 5 blog tools are registered only when SmartBlog is detected. Other blog modules are not supported. ps_check_shop_health reports "no blog" as info.

Commerce tools are missing.

Block 2 (panel: Sales) is off by default. Switch it on; the tools appear on the daily connector.

A tool disappeared mid-conversation.

The block or group is checked on every call. Someone switched it off, read-only mode was turned on, service mode or full customer data access expired, or the licence changed state.

Limits

Rate limit reached.

The module has hourly limits on tool calls, writes and file writes; the current values are in the Settings: security, alerts, limits card. Split large batches across hours or raise the limits in the Settings: security, alerts, limits card.

Batch refused with a limit error.

Per-call limits: ps_update_product_content 50, ps_update_category_content 20, ps_update_image_legends 100, ps_set_product_categories 200, ps_set_product_features 100, ps_update_prices 100, ps_update_stock 100, ps_manage_combinations 100, ps_set_product_redirect 100, ps_translate_catalog_items 200, ps_customer_service set_status 50, ps_db_query 200 rows, ps_db_execute 1000 rows backed up. Full table: Specification §11.1.

Writes

change_token expired, used or mismatched.

The token is an HMAC of tool, arguments and a hash of the "before" state, valid 30 minutes, single use. Repeat with identical arguments, or make a new preview.

Execution blocked: data changed since the preview.

The "before" state hash no longer matches, for example because of a back-office edit, an import or a feed module. Make a new preview.

Price change refused.

ps_update_prices refuses price 0 and changes above 30% without allow_big_change. ps_manage_specific_prices and ps_manage_catalog_price_rules require allow_big_change above 90% reduction (warning above 50%). Claude should set the flag only after the merchant approved that size of change.

Cart rule created but not active / can't delete.

ps_manage_cart_rules creates rules inactive by design; use action=set_active. There is no delete action; deactivate instead, or delete in the back office. A rule without a code needs auto_apply.

Validation error on save.

ObjectWriter validates each field with the class rules (validateField, isCleanHtml, lengths). Product names can't contain <>;=#{} and are limited to 128 characters. The message names the field.

Another module doesn't react to Claude's change.

ObjectWriter calls update(), which fires actionObject<Class>Update* (and actionProductSave / actionProductUpdate for products). Modules that listen only to back-office form hooks won't see the change. ps_check_shop_health lists them.

Permission denied.

ExecutionContext::requirePermissions checks the connector employee per tab and action, for example AdminCartRules add/edit. Switching a group or block on grants the matching permissions; if a profile was edited by hand, ps_get_shop_info lists what is missing. On some PrestaShop versions modules ignore saves by an employee without "view" on modules; the Start card offers a one-click fix.

Revert refused.

ps_revert_change can't undo: deleting a product photo, a product that already appears in an order (a created product is reverted by deleting it), module uninstall, DDL in ps_db_execute, URL changes (use a new ps_change_url). Encrypted history entries need the key file; without it they can't be reverted.

URLs

URL change blocked.

ps_change_url refuses when the canonical redirect is 302 (Shop Parameters > Traffic & SEO, set 301), developer mode is on (_PS_MODE_DEV_), or a module overrides routes (UrlGuard; ps_check_shop_health names it). Blog URL changes need "301 redirects for the blog" on in the settings.

Redirect refused by ps_manage_redirects.

The preview accepts only sources that return 404 or 410 now (an address that still works is refused) and targets that return 200 on the shop's domain. Chains (target is itself redirected) and loops are blocked. Up to 100 items per add, 100 IDs per disable/enable; source up to 1,024 characters, target URL up to 2,048. There is no delete: use disable, or undo through the change history. The tool needs a licence; Audit has only ps_list_redirects.

Files, theme and cache

Change not visible after a theme write.

Run ps_clear_cache (scope smarty; all also clears Symfony cache). Purge full-page cache modules and CDN cache separately.

Smarty validation error.

Only whitelisted tags and modifiers are allowed, then a test compile; {php}, {include_php} and static class access are refused. Nothing was saved.

"search must appear exactly once".

Use a longer fragment or write the whole file with content.

File access denied in block 4 or 5.

Paths must be relative, without .., resolve inside the zone (realpath) and have a text extension. Always denied: parameters.php/yml, settings.inc.php, .env*, keys and certificates, SQL dumps and .bak, .git, var/logs, upload, download, the module's private directory and the module itself.

PHP file write refused.

The syntax check (token_get_all(TOKEN_PARSE)) found a parse error. Runtime errors (for example an undefined function) are not detected, which is why every PHP write has a backup and the rescue key exists.

Restore after a broken change.

ps_list_file_backups, then ps_restore_file_backup (backs up the current version first), then ps_clear_cache. If the back office is down: open the rescue address and enter the rescue key; it restores connector-changed files and switches service mode off, but doesn't touch the database.

SQL (block 5)

Query refused.

One statement only, no comments hiding content. Always blocked: employee, session, access and profile tables, configuration (use ps_config), webservice and API tables, connector tables, file and MySQL user operations. Personal-data tables only at customer data level pseudo (masked) or full.

ps_db_execute rolled back.

More rows changed than declared, or more than 1000 rows would need a backup. Narrow the WHERE or split the change.

Known issues in 2.5.1 and their status in 2.6.0

Report a problem

Send to [email protected]: domain, PrestaShop and PHP versions, module version, package (paid or Audit), connector type, tool name, exact error text, time. Send only the token prefix, never the full token.

---

PrestaShop is a registered trademark of PrestaShop SA. Claude is a trademark of Anthropic. TellMyShop is not affiliated with either.