PrestaShop 9.2 Upgrade Headache: Solving the 'quick_access' Feature Flag Error

PrestaShop 9.2 Upgrade Headache: Solving the 'quick_access' Feature Flag Error

Upgrading a PrestaShop store to a new major version, like 9.2, can sometimes present unexpected challenges. A common issue that emerged during recent upgrades involves a specific database error related to feature flags, leading to a distorted frontend and an incomplete migration. This community insight delves into a forum thread where a user encountered the dreaded "The feature flag quick_access doesn't exist" error and how the community collaboratively worked towards a solution.

The Initial Problem: A Distorted Frontend and a Cryptic Error

The user, raunharman, reported an immediate error after upgrading to PrestaShop 9.2: "The feature flag quick_access doesn't exist." While the frontend was still accessible, it appeared distorted, indicating a deeper underlying issue. Despite clearing the cache in var/cache and using PHP 8.3-FPM, the problem persisted.

Diagnosing the Incomplete Database Migration

The expert advice from Knowband Plugins quickly pinpointed the likely cause: an incomplete database upgrade. The quick_access feature flag is a new entry expected in the ps_feature_flag table during the PrestaShop 9.2 database migration step. If this entry is missing, it signifies that the database part of the upgrade did not finish successfully.

Key diagnostic steps suggested included:

  • Checking PS_VERSION_DB: Verify the PS_VERSION_DB entry in the ps_configuration table. If it still showed an older version despite the core files being updated to 9.2, the database upgrade definitely failed.
  • Reviewing Upgrade Logs: The most crucial step was to examine the upgrade logs (typically found in your-admin-folder/autoupgrade/logs/, in files ending with -update.txt). Users were advised to search for specific phrases like "The execution of the query failed" or "Warning detected during update" and to locate references to 9.2.0.sql. These entries would reveal which SQL statements failed and why.

Uncovering the Missing Feature Flag Inserts

After diligent log analysis, it became clear that the upgrade process, while completing the file transfer, sometimes failed to execute certain critical SQL queries. Another user, venditdevs, provided concrete examples of the missing INSERT statements that define the new feature flags:

INSERT INTO `ps_feature_flag` (`name`, `type`, `label_wording`, `label_domain`, `description_wording`, `description_domain`, `state`, `stability`) VALUES ('quick_access', 'env,dotenv,db', 'Quick access', 'Admin.Advparameters.Feature', 'Enable / Disable the migrated quick access page.', 'Admin.Advparameters.Help', 0, 'stable')

And potentially for other features:

INSERT INTO `ps_feature_flag` (`name`, `type`, `label_wording`, `label_domain`, `description_wording`, `description_domain`, `state`, `stability`) VALUES ('hook_module_v2', 'env,dotenv,db', 'Hook a module', 'Admin.Design.Feature', 'Enable / Disable the migrated Hook a module form page.', 'Admin.Design.Help', 0, 'stable')

These inserts are part of the upgrade/sql/9.2.0.sql script, which should run for any shop upgrading to 9.2.0.

The Resolution and Important Caveats

Raunharman eventually resolved the issue by updating the missing entries in the ps_feature_flag database table, guided by Google AI. This highlights the growing role of AI in troubleshooting, but also the importance of understanding the underlying problem.

However, Knowband Plugins provided a critical clarification: simply adding the quick_access row manually to the database might resolve the immediate error, but it doesn't automatically complete all related upgrade steps. The 9.2 upgrade also involves a PHP step (ps_920_quick_access_tab()) that moves the Quick Access tab under Advanced Parameters and creates its necessary permissions. If this PHP step didn't run, the Quick Access page might still be missing or inaccessible even after the database row is added.

Other crucial steps for a complete fix include:

  • Clearing both theme and browser caches.
  • Checking for module or theme overrides that might still be expecting the old quick-access flag.

Key Takeaways for PrestaShop Merchants and Developers

This thread offers invaluable lessons for anyone undertaking a PrestaShop upgrade:

  1. Always Backup: Before any major upgrade, a complete backup of both files and the database is non-negotiable.
  2. Scrutinize Upgrade Logs: Do not just rely on a 'success' message. Thoroughly review the upgrade logs for any warnings or failed queries.
  3. Understand Database Changes: Be aware that major upgrades involve significant database schema changes. Familiarity with PrestaShop's database structure can aid in troubleshooting.
  4. Manual Intervention Might Be Necessary: In cases of incomplete database migrations, manual SQL execution might be required, but always proceed with caution and a fresh backup.
  5. AI as a Tool: AI can be a helpful assistant in diagnosing and suggesting fixes, but human expertise is still vital for validation and understanding the broader implications.

The collaborative effort in this thread underscores the strength of the PrestaShop community in tackling complex migration challenges, providing actionable insights for a smoother upgrade experience.

Start with the tools

Explore migration tools

See options, compare methods, and pick the path that fits your store.

Explore migration tools