This documentation always describes the current state of the main branch.
Error messages from the server appear in the tool's response and, for startup errors, on the process's stderr.
Symptom: The server does not show as connected in Claude Code, no tools are available.
Start it directly as a test: node ~/.claude/mcp-servers/shopwareadmin/dist/index.js. It then waits on stdin. If it aborts, the reason is on stderr:
| Message | Cause and fix |
|---|---|
Missing required environment variable: <NAME> |
A required variable is missing. Check the .env in the deployment directory (see Installation). |
Invalid SHOPWARE_URL: ... |
Not a valid URL, for example without https://. |
Invalid WIKIJS_BASE_URL: |
The variable is missing or not a URL. Set any valid URL, it is not used. |
CACHE_TTL_... must be positive |
One of the cache variables is 0 or negative. Remove it or set a positive value. |
Invalid JSON in content-profiles.json ... |
The file is not valid JSON. |
Invalid content-profiles.json at ... |
A field violates the schema, the message lists every field. See Configuration. |
Further points: is dist/ up to date (npm run build)? Is Node.js 20 or newer installed? Is the .env found (deployment directory first, then working directory)?
Symptom: Response with AUTH_FAILED.
| Message | Meaning |
|---|---|
Invalid client credentials |
Shopware answers with 401. Client ID or client secret are wrong. |
OAuth2 authentication failed: <status> |
Another error status from /api/oauth/token. Check that the integration is active and the URL belongs to the shop. |
OAuth2 token request timed out |
No response within 15 seconds. Check reachability and network. |
Symptom: API_ERROR with httpStatus: 403.
The integration lacks permission for the addressed entity. The entities needed per area are listed under Configuration. Writing tools need write permissions.
Shopware API request timed out after 30s: the shop answers too slowly. Retry later, the error is marked as retryable.RATE_LIMITED: Shopware is throttling. The server has already retried three times with delays, wait a few seconds.mail_template_send_test, RATE_LIMITED means the server's own limit of 5 per template and 10 in total per minute. The message names the wait time.Symptom: A change made in the Shopware admin does not show up in the tool, or an entry is not found.
Single lookups and some lists are cached in the server's memory:
| Data | Cache duration |
|---|---|
Product (product_get), medium, flow, cross-selling (single lookup) |
5 minutes |
| Categories, manufacturer list without search, properties, snippets, mail templates | 10 minutes |
Order (order_get) |
2 minutes |
| Product, media, order, flow, mail template and SEO URL lists, searches | no cache |
Restarting the server clears the cache. The server invalidates affected entries itself when it changes something. category_update clears the entire cache.
Also check: products are inactive after product_create. category_list hides inactive categories unless includeInactive is set.
| Symptom | Cause and fix |
|---|---|
Unknown content style: "<name>". Available: ... |
style does not name an existing profile. The message lists the valid names. |
| Always the same style | The category name does not match a key in categoryMapping exactly (case-sensitive), so defaultProfile applies. |
| New profiles are not picked up | The file is read only at startup. Restart the server. Also check which file is found: CONTENT_PROFILES_PATH, then deployment directory, then working directory. |
| No snippets in the response | The profile has includeSnippets: false or the call sets includeSnippets: false, so the server offers none. Or no active snippets exist, or the passed snippetIds do not match active snippets. |
API error with snippets or snippet_list |
The plugin providing the mmd-product-snippet entity is missing in the shop (or the integration lacks read permission). With includeSnippets: true content generation then fails with an API error already, it does not simply return an empty list. |
wikiUrl is null |
Expected, the field has no function. |
Symptom: Failed to upload media from URL or the URL is rejected.
Internal/private network URLs are not allowed: the URL points to an internal address, see Security.| Message or code | Meaning |
|---|---|
PRODUCT_NUMBER_EXISTS |
The product number is taken. |
INVALID_INPUT with details |
A parameter violates input validation, field names the parameter. |
Unknown tool: <name> |
The tool does not exist. |
Failed to send test mail |
Shopware could not send. Check the mail configuration in the Shopware admin. |
Product/Order/... not found |
The record does not exist or the ID is wrong. |
Error: fetch failed |
Network error between server and shop. |
Does the server work with Shopware 5? No. It uses the Shopware 6 Admin API.
Can Claude change orders? No. The order tools are read only.
Can the server serve several shops? One instance reads exactly one set of credentials and one default sales channel. For further shops you register further instances with their own configuration under another name.
Do products appear in the shop immediately? No. They are created inactive and only activated with product_set_active.
Where is the successor? See the status note on the overview page.