Deutsche Version

Back to overview

Sylius Admin: Troubleshooting

This documentation always describes the latest published version.

Server shows failed

Symptom: In /mcp, syliusadmin-stage-mcp or syliusadmin-prod-mcp shows failed and no tools are available.

Check:

1. Is it only the prod server, right after installation? Then that is expected, because prod/.env does not contain credentials yet.
2. Are SYLIUS_ENVIRONMENT, SYLIUS_BASE_URL, SYLIUS_ADMIN_EMAIL and SYLIUS_ADMIN_PASSWORD set in the environment's .env? If one is missing, startup aborts with a message naming the variable and the file that was read.
3. Does the file ~/.claude-plugin-syliusadmin/<stage or prod>/.env exist? If not, startup aborts; /syliusadmin:setup creates it.
4. Does SYLIUS_ENVIRONMENT in the file match the folder (stage in the folder stage, prod in the folder prod)? Otherwise the server refuses to start.
5. Does the venv exist at the path the launcher expects?

Solution for 5: bin/run-server starts the interpreter from ~/.claude-mcp-syliusadmin/venv (Windows: %USERPROFILE%\.claude-mcp-syliusadmin\venv), but the setup skill creates the venv under ~/.claude-plugin-syliusadmin/venv. Create it at the expected path:

python3 -m venv ~/.claude-mcp-syliusadmin/venv
~/.claude-mcp-syliusadmin/venv/bin/pip install -r <plugin-directory>/requirements.txt

Then restart Claude Code.

Login fails

Symptom: Tool calls fail with "Sylius-Login fehlgeschlagen" and an HTTP status.

Check:

1. Are SYLIUS_ADMIN_EMAIL and SYLIUS_ADMIN_PASSWORD correct? The message contains only the status, never the data.
2. On stage: does SYLIUS_API_KEY match exactly the value the stage instance expects? The header is sent during login as well.
3. Can the machine reach SYLIUS_BASE_URL (certificate, firewall, VPN)?
4. Does the instance answer with HTTP 500 and "error occurred while trying to encode the JWT token"? Then the JWT key pair is missing on the Sylius side. That is a server configuration issue, not a credentials error.

HTTP 403 "Access Denied" on every tool

Symptom: Login works, but every call ends with HTTP 403.

Solution: The admin user lacks the role ROLE_API_ACCESS. ROLE_ADMINISTRATION_ACCESS alone is not enough. Add the role in the roles field of the sylius_admin_user table, see Configuration.

SyliusScopeError

Symptom: A tool fails with "außerhalb des erlaubten Scopes", "kein DELETE" or "read-only".

Explanation: This is intended. The server blocks orders, customers, promotions and admin users as well as every delete except for marketplace links. Channels and input field definitions are read-only. See Security.

Image upload is disabled

Symptom: add_product_image or add_taxon_image with image_path fails immediately with a note about SYLIUS_IMAGE_UPLOAD_BASE_DIR.

Solution: Set the variable in the .env to an absolute, existing path and restart. The image path must lie inside this directory and exist on the machine of the MCP server. If the image is already on the CDN, use cdn_url, which works without this setting.

cdn_url is rejected by the shop

Symptom: add_product_image with cdn_url returns a Sylius error.

Check: Is the plugin sylius-cdn-product-images installed in the shop? Without it, this route does not exist. variant_codes are not allowed together with cdn_url.

Product cannot be activated

Symptom: set_product_active or update_product with enabled=true is rejected with a note about missing variants.

Solution: First create at least one variant with add_variant. Without a variant the product page in the shop would have no price and crash with HTTP 500.

add_variant is rejected

Symptom: Message about missing channel prices or option values.

Solution:

• channel_pricings needs a price for every channel the product is assigned to (get_product shows them).
• If the product has options, option_value_codes needs exactly one value per option of the product.
• Variant codes must be unique shop-wide; the value code of an option is unique across all options.

Shipping method is rejected

Symptom: create_shipping_method or update_shipping_method fails on the configuration.

Solution: For flat_rate and per_unit_rate, configuration needs an entry for every channel of the shop (list_channels), not only those named in channel_codes. If you update configuration, rules or channel_codes, that replaces the complete data.

SEO fields are not saved

Symptom: metaTitle, canonicalPathOverride, robotsIndex or robotsFollow are accepted but missing when read back.

Explanation: The fields only exist where the shop's translation classes use the traits of the sylius-seo-suite-pro plugin. Otherwise the API ignores them without an error. Always read the translation back.

update_product does not change the options

Symptom: option_codes is accepted, but the product's option list stays the same.

Explanation: Sylius only applies the change as long as no variant of the product has option values, and does not report that as an error. Remove the variants first (in the Sylius admin).

FAQ

What is MCP? The Model Context Protocol is an open standard that lets Claude talk to external services through tools. This server is the bridge to the Sylius Admin API and runs locally over stdio.

Can Claude process orders? No. There are neither tools for it nor access through the allowlist.

Why can't I delete anything? That is intentional: deleting stays in the Sylius admin. Marketplace links are the exception. Shipping methods can be archived.

Can I use stage and prod at the same time? Yes, the plugin starts both servers at the same time. Each server serves exactly one environment.

Does the server run on Windows? The setup skill and the launcher scripts (bin/run-server.cmd) account for Windows, including the Python lookup via py -3.