Common Issues

A playbook for the concrete errors editors and admins hit most often. Every entry follows the same shape: Symptom (what you see), Cause (what it actually is), Solution (what to do). Work through the steps in order — the first step is the most likely cause.

1. Widget does not appear in the frontend

Symptom: A Widget is placed on the page, the Pagebuilder shows it in the Preview, but the live site renders an empty Row.

Cause: The Widget is hidden by a responsive-visibility flag, or the page is not published.

Solution:

1. Open the Widget in the Pagebuilder and check the Visibility section. Confirm at least one of Desktop, Tablet, or Mobile is enabled. If all three are disabled, the Widget is hidden on every breakpoint.
2. Confirm the page itself is published — the top bar must not show the DRAFT badge. If it does, click Publish.
3. Clear the API cache under Administration → Cache → Clear cache.

2. Shopware 6 categories are empty

Symptom: The category teaser widget or the SW6 menu renders with no categories. A console error may say SW6: empty root_category_id response or circuit breaker open.

Cause: The Shopware connection is misconfigured, the access key rotated, or the Sales Channel's root category ID is wrong.

Solution:

1. Open E-Commerce → Shopware 6 → Connection and click Test connection. A red lamp means the credentials are rejected — reissue the access key in the Shopware admin and paste it in.
2. Check Sales Channel ID and Root Category ID. Both UUIDs come from the Shopware admin under Sales Channels → {your channel}. A typo here yields an empty category tree.
3. If the circuit breaker is open, wait 60 seconds or click Reset circuit breaker on the connection page. The breaker opens after 5 consecutive API failures and auto-closes after the cooldown.
4. Trigger a category sync manually under E-Commerce → Shopware 6 → Categories → Sync now.

3. Sitemap is out of date

Symptom: Pages published yesterday still do not appear in /sitemap.xml. Search engines keep indexing old URLs.

Cause: The scheduled sitemap task is stuck, disabled, or never ran.

Solution:

1. Open Administration → Task Manager → Scheduled Tasks. Find Sitemap Generation and check Last Run — should be within 24 hours.
2. If the task is disabled, toggle it on.
3. If the task is enabled but has not run, click Run now. Watch the Queue tab for errors.
4. For Shopware 6 content, confirm sw6_config → last_sync is recent. Stale SW6 data will not enter the sitemap.
5. Clear the API cache; the sitemap endpoint itself is cached for 1 hour.

4. Pagebuilder loads endlessly

Symptom: Opening a page in the Pagebuilder shows the loading spinner for minutes. No error toast, no structure tree.

Cause: A corrupt draft blocks the snapshot load, browser cache holds stale JS, or APCu is empty and the first load is rebuilding catalogs.

Solution:

1. Hard-reload with Ctrl+F5 / Cmd+Shift+R to bypass the browser cache.
2. If the spinner persists, open the browser console and look for a 500 error on /api/backend/pagebuilder. A 500 usually points to a corrupt page_versions row.
3. Open Versions on the page. If the latest Draft has a weird timestamp or a (corrupt) marker, delete it — the Pagebuilder falls back to the previous Published version.
4. If APCu is empty, the first Pagebuilder load builds the widget catalog and takes 10-30 seconds. Subsequent loads are fast.

5. Email Marketing connection test fails

Symptom: The Test connection button on an email-marketing connection returns an error: 401 Unauthorized, 403 Forbidden, or invalid API key.

Cause: Wrong API key, missing data-center suffix (Mailchimp), or revoked credentials.

Solution:

1. Mailchimp: the API key must include the data-center suffix (-us21, -us5, etc.). Without it, all calls 401.
2. Brevo: regenerate the key in Brevo → SMTP & API → API Keys. Old keys silently stop working after provider maintenance.
3. Rapidmail: the provider uses Basic Auth — confirm both User and Password fields are filled.
4. Klaviyo: the key must have the full-access scope. A read-only key cannot subscribe users.
5. For Double-Opt-In flows, confirm a DOI template ID is configured on the Form — not just the connection.

6. Stripe or PayPal payment fails

Symptom: At checkout, the user clicks pay and gets an error — Payment could not be completed, Order creation failed, or a silent redirect back to the cart.

Cause: Webhooks are not registered, a Dev-Sandbox key is in use in Production, or the order was created but the payment capture never returned.

Solution:

1. Open E-Commerce → Payment Providers → Stripe (or PayPal). Confirm the keys are Live/Production keys, not Test/Sandbox.
2. For Stripe: the webhook endpoint must be registered in the Stripe dashboard pointing to https://{your-site}/api/shop/stripe/webhook. Without it, payments appear successful but the order stays in pending.
3. For PayPal: confirm the Return URL and Cancel URL are both HTTPS and match the production domain.
4. Check Log → Filter: Payment for the exact error. Card declines and fraud blocks leave clear entries.
5. If payments fail only in certain countries, check the currency and regional settings in the provider dashboard — some methods are geographically restricted.

7. Page redirects endlessly

Symptom: Opening a page in the browser loops forever. The browser eventually shows ERR_TOO_MANY_REDIRECTS.

Cause: A 301-redirect entry points to itself or to another URL that redirects back.

Solution:

1. Open SEO & Design → Redirects. Search for the page slug in both From and To columns.
2. Delete any entry where From and To resolve to the same URL (directly or transitively).
3. Confirm no url_rewrite entry conflicts with a redirect for the same slug — the rewrite wins, but if the rewrite target itself has a redirect, you get a loop.
4. Clear the API cache to drop cached redirect responses.

8. File upload fails with error 413

Symptom: Uploading a large image or video in the Media Manager returns 413 Payload Too Large or Request Entity Too Large. Small files upload fine.

Cause: PHP or the web server blocks the upload size. Three limits stack: PHP upload_max_filesize, PHP post_max_size, and the web server's body limit (client_max_body_size on nginx, LimitRequestBody on Apache).

Solution:

1. Ask your hoster or server admin to raise all three limits. A common safe set is upload_max_filesize=128M, post_max_size=130M, client_max_body_size=150M.
2. Restart PHP-FPM (or Apache) after the change.
3. The Backend shows the effective limit under Administration → General Settings → Upload Limit. If the value did not change after the edit, you edited the wrong php.ini — check phpinfo() for the active path.
4. For videos, consider linking to an external host (Vimeo, YouTube, S3) instead of uploading through the Backend.

9. Canonical URL points to the wrong category

Symptom: Google Search Console reports the wrong canonical URL for a Shopware 6 product. The product is in multiple categories, and the canonical points to the "wrong" one.

Cause: The canonical-category flag is not set, so the system picks the first category alphabetically.

Solution:

1. Open E-Commerce → Shopware 6 → Categories. Find the category you want to be canonical for the product.
2. Toggle Use as canonical category on.
3. Regenerate the product cache under Shopware 6 → Products → Rebuild cache. The new canonical appears in <link rel="canonical"> after the next page render.
4. If the product is in multiple canonical-flagged categories, the first one by sort_order wins.

10. User-Center item does not appear

Symptom: A plugin promises to add an entry to the shop user account (e.g. My Courses, My Certificates), but the account page does not show it.

Cause: The plugin is not installed, or the logged-in user does not meet the isVisible() condition the plugin registered.

Solution:

1. Open Administration → Plugin Manager and confirm the plugin is Installed and Active.
2. Log in as the end-user (not the Backend admin). User-Center items render in the frontend account page, not in the Backend.
3. Some items hide until the user has relevant data — e.g. My Courses is empty if the user bought no courses. Buy a test course or seed data.
4. Hard-reload the frontend to drop cached JS bundles.

11. Media Manager shows no files

Symptom: The Media Manager opens but the grid is empty, even though you know files exist.

Cause: An active folder filter, a permission filter, or a filename with characters that break the file-scan.

Solution:

1. Click All folders at the top of the folder tree to clear the current filter.
2. Clear the search field — a stale filter from a previous session persists in localStorage.
3. If the folder still looks empty but the disk has files, connect via SFTP and check for filenames containing ?, #, or control characters. Rename them to ASCII-safe slugs.
4. Run Administration → Task Manager → Rescan Media to rebuild the file index.

12. AI prompt returns nothing

Symptom: In any AI-powered field (SEO text, blog rewrite, layout generation), the spinner runs for a while, then returns empty or an error toast says AI request failed.

Cause: The AI connection is inactive, the API key is expired, or a rate limit kicked in.

Solution:

1. Open SEO & Design → AI Text Generation → Connections. The active connection must have a green lamp.
2. Click Test connection — a red lamp with 401 means the key is revoked. Regenerate in the provider dashboard (OpenAI, Anthropic, Google, Mistral) and paste it in.
3. Check the provider's usage / billing page. Spent credits or exceeded quotas return 429; the Backend shows this as a generic failure.
4. For long outputs (layout generation, long blog text), the request can take 30-60 seconds. Wait past the initial spinner — the Backend polls for up to 5 minutes before giving up.
5. If the connection works but one specific feature fails, open AI Features reference and confirm the feature is mapped to a connection with the right capability (vision, JSON mode).

13. Sitemap contains deleted pages

Symptom: /sitemap.xml lists pages that were deleted weeks ago. Search engines crawl 404s.

Cause: The page was deleted but the sitemap task ran before the delete was committed, or a 301-redirect keeps the URL alive in the task's output.

Solution:

1. Trigger a fresh sitemap run under Administration → Task Manager → Scheduled Tasks → Sitemap Generation → Run now.
2. Check SEO & Design → Redirects for a stale redirect pointing at the deleted slug. A redirect keeps the source URL in the sitemap as the redirect origin.
3. If the deleted page had child pages, restore the parent briefly, delete the children explicitly, and then re-delete the parent. Orphaned children sometimes keep ghost entries.

14. Cache clear has no effect

Symptom: You clicked Clear cache, a success toast appeared, but the frontend still serves the old content.

Cause: A second cache layer is in play — CDN, nginx proxy cache, or browser cache. The Backend only clears its own APCu response cache.

Solution:

1. Hard-reload with Ctrl+F5 / Cmd+Shift+R.
2. If a CDN sits in front (Cloudflare, Fastly, CloudFront), purge it from the CDN's dashboard. Your hoster may provide a wrapper for this.
3. On nginx-cached setups, fastcgi_cache_purge must be wired up — ask your server admin if it is. Restarting PHP-FPM does NOT clear nginx's cache.
4. For Custom CSS changes, run Recompile CSS in addition to the regular cache clear — Custom CSS lives in a separate compiled file.

15. Scheduled publish did not go live

Symptom: A Draft was scheduled for 10:00, but at 10:15 the page is still showing the old version. No error is visible.

Cause: The scheduled-tasks worker is not running, the server clock drifted, or the Draft became invalid between scheduling and the publish time.

Solution:

1. Open Administration → Task Manager → Scheduled Tasks. Publish Scheduled Pages must show a recent Last Run (within 5 minutes). If it is stale, the worker is not running — contact your hoster.
2. Check server time: Administration → General Settings → Server Time. If it drifts by more than a minute, schedules fire at the wrong wall-clock time.
3. Open the page in the Pagebuilder. If the Draft has a validation error (broken Widget, missing required field), it cannot publish automatically. The task logs the skip under Log → Filter: Scheduled Publish.
4. Reschedule the publish manually to test.

See also

• FAQ — short Q/A for everyday questions
• Glossary — terminology reference
• Task Manager — queue + scheduled-task diagnostics
• Cache — clear API response cache and CSS cache
• Log — filter system log entries by type