The first steps
An update was aborted, or afterwards the store shows errors, blank pages or an Administration that will not load. What helps now is a fixed order of steps.
- 01
Turn on maintenance mode
For all sales channels. That way no orders come in to a half-updated store.
- 02
Save the current state
Even broken, it is what you troubleshoot from.
- 03
Read the logs
Before you change anything. The message usually names the spot.
- 04
Decide
Repair if the cause is clear and quick to fix. Restore if it is not.
You turn on maintenance mode in the settings of each sales channel, or on the console for all of them at once. In the channel settings you also allow your own IP address, so you can still see the store during maintenance.
bin/console sales-channel:maintenance:enable --allWhere it usually goes wrong
If the Administration does not load, an extension often ships outdated Administration files. Updating or temporarily deactivating it helps.
Incompatible extensions
A plugin does not support the new version yet. Especially extensions that reach deep into checkout, payment or shipping.
Composer conflicts
If you update with Composer, you get “Your requirements could not be resolved” when extensions require different package versions.
Aborted migrations
An update restructures the database. If a migration aborts, the database is stuck between the old and the new state.
Theme not recompiled
The Storefront looks unstyled or individual elements are missing.
Caches and OPcache
The server still delivers parts of the old code. The errors go away once all caches are cleared and PHP is restarted.
Background processes
The queue and scheduled tasks keep running with old code: emails, indexing or exports get stuck.
Narrowing down the cause
Shopware writes errors to log files in the var/log folder, in a production store to files like prod-<date>.log. On top of that there is the web server’s error log. The message usually names the class or file, and through it the plugin.
One command at a time, with a look at the log in between. If you run everything at once, you will not know afterwards what helped.
bin/console plugin:refreshReload the extensions.bin/console plugin:listAll extensions with version and status.bin/console plugin:deactivate <Name>Switch off a suspicious extension.bin/console cache:clearClear the cache.bin/console theme:compileRecompile the theme.bin/console dal:refresh:indexRebuild the indexes when search or categories show wrong results.bin/console messenger:stop-workersStop the background processes so they restart with the new code.
Before the update bin/console system:update:prepare, afterwards bin/console system:update:finish. The latter runs the database migrations. If this step was forgotten or aborted, that alone is often the cause.
Going back only works with files and database together
An update changes not only files but, through its migrations, the database too. Old files on a database that has already been restructured lead to new errors.
Without a backup from right before the update, the only option is to repair forward: find the cause, update or replace extensions, run the migrations again. That usually takes longer and needs experience with Shopware.
Files and database from the same backup
Taken right before the update. Orders placed after it will be missing from the store afterwards.
It keeps such orders from coming in. Anything ordered between the backup and maintenance mode has to be reconciled with your payment provider and your inventory system.
Security updates cannot wait
A failed update is no reason to update less often from now on.
Shopware publishes security fixes as patch releases, recognizable by the last digit of the version number. Older versions get selected fixes through the security plugin, which does not replace a current version. Two examples from 2026:
Store API
Under certain conditions, takeover of the administrator account and code execution, especially in headless stores.
Source: Sansec, August 2026App credentials
CVE-2026-31889: takeover of the credentials of installed apps.
Source: GitHub Security Advisory, 2026So: apply security updates promptly and tested, not blindly. How to do that without downtime is covered in the guide How to update Shopware 6 without putting your store at risk.
Rehearse, but not with real customer data
The best insurance against a failed update is a dress rehearsal on a copy of the store. There it is allowed to fail and gets fixed before the live store takes a hit.
From a data protection point of view, a copy with real names, addresses and orders is a second database full of personal data, often less well protected than the live store.
| Field | Live store | Copy |
|---|---|---|
| Name | Jane Example | Customer 4711 |
| jane@example.com | customer4711@test.invalid | |
| Address | 1 Sample Road | 1 Test Street |
| Order | 3 items, €129.00 | 3 items, €129.00 |
Made-up sample data. Products, prices and order structures stay, people do not.
How I prevent this with the Doppelgänger
For my clients, I apply every Shopware update to the Doppelgänger first, an exact copy of the store on a dedicated server in Germany.
Anonymized copy
Customer data is anonymized on every copy.
Checked through to checkout
I check extensions, theme and background services, and I place orders through to checkout, using the payment providers’ test modes.
Live, reversible at any time
Only the checked state goes live, within a few minutes. Every release is a version of its own, and the previous state is back in seconds.
Tested every morning
Every morning a test order runs through the live store up to payment.
What that looks like in detail is on the page The Doppelgänger for Shopware.
From a client: JuCad works with the Doppelgänger: every update and every new feature runs on the copy of the store first and goes live only after testing.
Since our store got its Doppelgänger, where Julian checks every update and every change first, the store has been running absolutely smoothly. Updates are no longer a big project we keep putting off. We see and test new features there before they go live, and only approve them once everything is right. It has made our work noticeably more productive.
Quick answers.
What do I do first when a Shopware update fails?
Turn on maintenance mode for all sales channels so that no orders come in to a half-updated store. Then save the current state for troubleshooting and look at the logs under var/log and at the web server's error log.
Can I just copy the old files back?
No. Through its migrations, an update also changes the database. Old files on a new database structure lead to further errors. Going back only works with files and database from the same backup, ideally taken right before the update.
Which extensions cause the most problems during updates?
Extensions that reach deep into checkout, payment or shipping, and custom plugins whose vendor does not support the new Shopware version yet. Before every update, it pays to check the compatibility information of all installed extensions.
After the update, the store looks unstyled. What happened?
Usually the theme was not recompiled after the update, or caches are still delivering old files. Recompiling the theme and clearing the caches fixes this in many cases. If the error remains, it is often a theme extension that does not fit the new version.
How urgent are Shopware security updates?
Very urgent. Shopware publishes security fixes as patch releases, and for older versions through the security plugin. In 2026, fixes included a vulnerability in the Store API with a possible takeover of the administrator account and a vulnerability affecting app credentials. Updates like these should be applied promptly, but tested.
May I test updates on a copy with real customer data?
I advise against it. From a data protection point of view, a copy with real names, addresses and orders is a second database full of personal data, often less well protected than the live store. For testing, a copy with anonymized customer data is enough.