Shopware Troubleshooting

Shopware 6 — Troubleshooting and Gotchas

See the shopware skill for the map of Shopware skills.

Common Gotchas

1. SW6 DAL — never use raw SQL for entity data. Use repositories. Direct DBAL only for reporting/aggregations.
2. SW6 context — always pass Context or SalesChannelContext down; never instantiate Context::createDefaultContext() in production code (bypasses ACL).
3. SW5 cache — call $context->scheduleClearCache() in install/update/activate or changes won't appear.
4. SW6 Twig — use {% sw_extends %} not {% extends %} for storefront templates.
5. SW6 JS — PluginBaseClass comes from window, not from an import path.
6. Don't call .first() on aggregation results — you need the EntitySearchResult object.
7. Upsert requires an ID — without an ID, every upsert() call creates a new record.
8. ManyToMany updates — update through the owning entity, not through the mapping repository.
9. Custom entity tag — shopware.entity.definition entity attribute must match ENTITY_NAME constant.
10. CMS initElementConfig() — must be called in both component AND config; skipping causes undefined config values.
11. Store API abstract pattern — always create Abstract → Concrete → optional Decorators; inject AbstractXRoute in consumers.
12. ArrayStruct + Twig .count — ArrayStruct implements \Countable. In Twig, .count resolves to the count() method (returns number of keys), not to a key named count. Use a different key name like total to avoid collision: new ArrayStruct(['total' => $value]).
13. CMS slot getData() types — $slot->getData() for a category-navigation CMS element returns a Tree object, not a generic Struct. Use $data->getTree() (returns TreeItem[]), not $data->get('tree').
14. Sidebar filter styles must scope to desktop — Custom SCSS for .is--sidebar and .cms-element-sidebar-filter .filter-panel-wrapper must be wrapped in @include media-breakpoint-up(lg). Without this, the mobile offcanvas filter panel breaks because display: block overrides the offcanvas hidden state.
15. .nav-main is a sibling of .header-main — The main navigation bar is outside the header element in the DOM. It can be made position: sticky independently without affecting the header (logo, search, cart).

Common Problems & Solutions (SW6)

Plugin / Service Issues

Template / Frontend Issues

Cache & Performance Issues

Installation / Upgrade Issues

Frequently Used Dev Tools & Plugins (SW6)

.env.local for Development

dotenvCopy code
APP_ENV=dev
APP_DEBUG=1
APP_SECRET=your-generated-secret
DATABASE_URL="mysql://root:root@db:3306/shopware"
SHOPWARE_HTTP_CACHE_ENABLED=0
SHOPWARE_HTTP_DEFAULT_TTL=0

Useful bin/console Commands

bashCopy code
bin/console debug:container | grep product          # Find services by keyword
bin/console debug:event-dispatcher | grep cart      # Find events by keyword
bin/console debug:router                             # All registered routes
bin/console feature:config                           # Show feature flags
bin/console system:config:get SwagExample.config.myKey
bin/console system:config:set SwagExample.config.myKey value
bin/console sales-channel:list
bin/console user:change-password admin