|
| 1 | +--- |
| 2 | +nav: |
| 3 | + title: Deployment Helper Troubleshooting |
| 4 | + position: 20 |
| 5 | + |
| 6 | +--- |
| 7 | + |
| 8 | +# Deployment Helper Troubleshooting |
| 9 | + |
| 10 | +This page highlights common failures when running `vendor/bin/shopware-deployment-helper run`, and provides guidance for resolving them. For the full command, configuration, and environment-variable reference, see [Deployment Helper](deployment-helper.md). |
| 11 | + |
| 12 | +## Getting more detail |
| 13 | + |
| 14 | +`run` returns a non-zero exit code on failure and prints each step's output. Read the output above the failure to find the failing command, and re-run that Shopware console command directly (for example, `bin/console system:update:finish`) to see its full error. |
| 15 | + |
| 16 | +## The deploy fails to reach the database |
| 17 | + |
| 18 | +**Symptom:** the run ends with a database connection error, or `Could not connect to database`. |
| 19 | + |
| 20 | +The helper waits for the database, retrying up to 10 times with a one-second pause between attempts. If it still cannot connect, it fails. |
| 21 | + |
| 22 | +Check if: |
| 23 | + |
| 24 | +- `DATABASE_URL` is correct and reachable from the deploy environment (host, port, credentials). |
| 25 | +- the database service is actually up before the helper runs. In container setups, order startup so the database is ready, or add your own wait. |
| 26 | +- TLS is required, and `DATABASE_SSL_CA` / `DATABASE_SSL_CERT` / `DATABASE_SSL_KEY` are set. To bypass server-certificate verification (non-production only), set `DATABASE_SSL_DONT_VERIFY_SERVER_CERT`. See [Environment variables](deployment-helper.md#environment-variables). |
| 27 | + |
| 28 | +## A step times out on a large shop |
| 29 | + |
| 30 | +**Symptom:** a step is killed after 300 seconds. |
| 31 | + |
| 32 | +Each step has a timeout (default 300s). Raise or disable it: |
| 33 | + |
| 34 | +```bash |
| 35 | +vendor/bin/shopware-deployment-helper run --timeout=900 |
| 36 | +# or disable entirely: |
| 37 | +vendor/bin/shopware-deployment-helper run --timeout=null |
| 38 | +``` |
| 39 | + |
| 40 | +You can also set `SHOPWARE_DEPLOYMENT_TIMEOUT` in the environment. The `--timeout` option takes precedence. |
| 41 | + |
| 42 | +## Theme and assets were not pre-built in CI/CD |
| 43 | + |
| 44 | +The deployment artifact must already contain the compiled theme and installed assets. In CI/CD, build the artifact with `shopware-cli project ci` and deploy that output. |
| 45 | + |
| 46 | +At deploy time, run Deployment Helper with the theme and asset steps skipped so it only consumes the pre-built artifact: |
| 47 | + |
| 48 | +```bash |
| 49 | +vendor/bin/shopware-deployment-helper run --skip-theme-compile --skip-assets-install |
| 50 | +``` |
| 51 | + |
| 52 | +If the Storefront is missing assets after deployment, fix the CI build artifact or upload step. Do not compensate by compiling the theme or installing assets during deployment. |
| 53 | + |
| 54 | +## An update ran, but `system:update:finish` did not |
| 55 | + |
| 56 | +This is expected. The update-finish/migration step runs only when the Shopware version actually changed. If you redeploy the same version, that step is skipped by design. To force it, deploy an actual version change. |
| 57 | + |
| 58 | +## A one-time task keeps running every deploy |
| 59 | + |
| 60 | +A one-time task is only recorded as done after it succeeds. If it keeps running, it is failing partway through. Check the deploy output for its error: |
| 61 | + |
| 62 | +- Inspect state: `one-time-task:list`. |
| 63 | +- If the task's effect is already applied and you want to stop it: `one-time-task:mark <id>`. |
| 64 | +- To force a rerun: `one-time-task:unmark <id>`. |
| 65 | + |
| 66 | +## A config setting seems to have no effect |
| 67 | + |
| 68 | +Deployment Helper provides a configuration schema for `.shopware-project.yml`. Use it in your editor to validate the file while editing, so misspelled or misplaced keys are reported before deployment. |
| 69 | + |
| 70 | +Check if: |
| 71 | + |
| 72 | +- Your editor is using the schema and does not report any validation errors. |
| 73 | +- The key is nested under the correct section, for example `deployment:`. |
| 74 | +- You are editing the file the helper actually loads. If `SHOPWARE_PROJECT_CONFIG_FILE` or `--project-config` is set, that file wins over the auto-discovered one. |
| 75 | +- A `.shopware-project.local.yml` is overriding your value. Local files merge on top of the base file. See [Local configuration overrides](deployment-helper.md#local-configuration-overrides). |
| 76 | + |
| 77 | +## Extensions aren't being installed or updated as expected |
| 78 | + |
| 79 | +- Confirm `deployment.extension-management.enabled` is `true`. |
| 80 | +- Check the extension isn't listed under `exclude`, or set to `state: ignore` / `inactive` in `overrides`. |
| 81 | +- If extensions are managed by the Store or Administration instead, extension management may be intentionally disabled — reconcile the two so they don't fight. Prefer managing extensions from code (via Composer) or via the helper, not both. See [Extension management and Store-installed plugins](deployment-helper.md#extension-management-and-store-installed-plugins). |
| 82 | + |
| 83 | +## Store login or license refresh fails |
| 84 | + |
| 85 | +App installation and license refresh need valid Store credentials and a license domain. Verify: |
| 86 | + |
| 87 | +- `SHOPWARE_STORE_ACCOUNT_EMAIL` and `SHOPWARE_STORE_ACCOUNT_PASSWORD` (or `SHOPWARE_STORE_SHOP_SECRET`) are set. |
| 88 | +- A license domain is set, via `deployment.store.license-domain` or `SHOPWARE_STORE_LICENSE_DOMAIN`. |
| 89 | + |
| 90 | +## Fastly snippets aren't updating |
| 91 | + |
| 92 | +Automatic snippet deployment during `run` only happens when: |
| 93 | + |
| 94 | +- A `config/fastly` directory exists in the project, and |
| 95 | +- `FASTLY_API_TOKEN` and `FASTLY_SERVICE_ID` are set, and |
| 96 | +- `FASTLY_DISABLE_SNIPPET_UPDATE` is **not** set to `1`. |
| 97 | + |
| 98 | +To manage snippets manually, use the `fastly:snippet:*` commands. See [Fastly integration](deployment-helper.md#fastly-integration). |
| 99 | + |
| 100 | +## Need to completely reinstall |
| 101 | + |
| 102 | +If an environment is broken beyond repair, force a clean `install` from scratch. |
| 103 | + |
| 104 | +:::warning |
| 105 | +Setting `SHOPWARE_DEPLOYMENT_FORCE_REINSTALL=1` triggers a fresh `install` with `--drop-database`. This destroys existing data! Only use it in disposable environments, never in production. |
| 106 | +::: |
0 commit comments