Updating a Shopware project from 6.5 to 6.6 is more than a routine Composer update. Shopware 6.6 raises the system requirements and introduces changes that can affect project entry points, storefront JavaScript plugins, extensions, themes, and server configuration.

This guide combines Shopware's official update sequence with solutions to errors I encountered while upgrading real projects.

Before updating from Shopware 6.5 to 6.6

Do not begin with composer update on the production system. Prepare the project and a recovery path first:

Shopware recommends using Composer because this update method is more stable and avoids browser timeouts.

Official Shopware guide: Update from 6.5 to 6.6

The recommended Composer update sequence

Run the preparation command from the project root:

bin/console system:update:prepare

Then update the Shopware package constraints in composer.json to the target 6.6 version. Keep the versions of shopware/core, shopware/administration, shopware/storefront, shopware/elasticsearch, and other Shopware packages aligned.

Resolve and install the new dependencies:

composer update

When Composer has completed successfully, run the database migrations and finish the update:

bin/console system:update:finish

Finally, force-update the Symfony recipe configuration files:

composer recipes:update

The recipes command is easy to overlook, but it is part of Shopware's documented Composer update flow. Review the resulting configuration changes carefully before committing or deploying them, especially when the project contains custom Symfony configuration.

Official Shopware documentation: Updating Shopware with Composer

1. Fix “Class Shopware\Core\HttpKernel not found”

The update may stop immediately with this message:

Uncaught Error: Class "Shopware\Core\HttpKernel" not found

This usually means that the project's entry-point files still contain code from the older Shopware version. Compare and update these files with the versions from the exact Shopware 6.6 release you are installing:

For an update to Shopware 6.6.0.2, use the matching files from the 6.6.0.2 tag:

Shopware 6.6.0.2 public/index.php

Shopware 6.6.0.2 bin/console

Shopware 6.6.0.2 bin/shopware

Do not copy files from a different patch release without comparing them. After correcting the entry points, continue with the Composer update sequence described above.

2. Fix JavaScript plugins that no longer work

After the core update, custom storefront JavaScript may stop working even though the administration and storefront still load. In Shopware 6.6, custom plugins should be registered asynchronously. Open the main.js file in your theme or extension and replace the direct import with a dynamic import.

Before:

import ExamplePlugin from './plugins/example.plugin';
window.PluginManager.register('Example', ExamplePlugin, '[data-example]');

After:

window.PluginManager.register(
    'Example',
    () => import('./plugins/example.plugin'),
    '[data-example]',
);

The same change applies when overriding an existing plugin.

Before:

import MyListingExtensionPlugin from './plugin-extensions/listing/my-listing-extension.plugin';
window.PluginManager.override(
    'Listing',
    MyListingExtensionPlugin,
    '[data-listing]',
);

After:

window.PluginManager.override(
    'Listing',
    () => import('./plugin-extensions/listing/my-listing-extension.plugin'),
    '[data-listing]',
);

Shopware 6.6 upgrade guide: registering asynchronous JavaScript plugins

3. Fix Composer PHP version errors

Composer may stop dependency resolution with one of these messages:

Your Composer dependencies require a PHP version *
shopware/administration v6.6.1.0 requires php ~8.2.0 || ~8.3.0
Your php version (8.1.27) does not satisfy that requirement.

Check the PHP version used by the command line:

php -v

Make sure the command-line PHP version and the PHP version used by the web server both meet the Shopware 6.6 requirements. They can differ on servers with multiple PHP installations.

For Shopware 6.6.1.0, update the PHP constraint in the require section of composer.json when appropriate:

"php": "~8.2.0 || ~8.3.0"

Do not change the Composer constraint only to silence the error. Upgrade the actual PHP runtime first, then run Composer with that same supported version.

4. Fix an error when creating a media folder

After the update, creating a media folder may fail with:

CRITICAL: Uncaught Error: assert($levelField instanceof TreeLevelField)

Check which php.ini file is active and disable assertion evaluation in the production environment:

; don't evaluate assert()
zend.assertions=-1

Restart the relevant PHP-FPM or web server service after changing php.ini, then clear the Shopware cache and try the operation again.

Shopware documentation: PHP configuration tweaks

After the update

Before deploying the updated project to production:

If the update still fails, preserve the complete Composer or Shopware error output. The first exception in the log is usually more useful than the final generic error shown in the browser.

Ask about a Shopware update