Recover from component failure

Last update: 2023-04-27
  • Topics:
  • Cloud
    View more on this topic
  • Deploy
    View more on this topic
  • Created for:
  • Admin

This topic discusses how to recover if a component fails to deploy properly. Typical examples include components that have dependencies that are not met by your remote environment, such as incompatible PHP versions.

You can recover from a failed deployment in any of the following ways:

Clean, remove, and redeploy

To clean up from the previous deployment, you may need to identify the component that was added or updated and then remove it. First, log in to the remote environment and manually clear the contents of the var directory. Then remove the component from the composer.json file and redeploy the environment.

To clean the var directories:

  1. On your local workstation, change to your project directory.

  2. Use SSH to log in to the remote environment.

    magento-cloud ssh
  3. Clear the var directories.

    rm -rf var/*
  4. Log out.

To remove the component:

  1. On your local workstation, change to your project directory.

  2. Clear the cache.

    composer clear-cache
  3. Remove the component from the composer.json file.

    composer remove <component-name>:<version>

    If the following message displays, you do not need to do anything further:

    Package "<name>:<version>" listed for update is not installed. Ignoring.
  4. Wait while the dependencies are updated.

  5. Add, commit, and push code changes.

    git add -A
    git commit -m "<message>"
    git push origin <environment-ID>

The deployment process begins when you perform a merge, push, or synchronization of your environment, or when you trigger a manual redeployment, during which the Commerce application is in maintenance mode. For a Production environment, Adobe recommends completing this work during off-peak hours to avoid service disruptions.

See more about restoring an environment without a snapshot in Restore an environment.


For help with stuck deployments, use the Adobe Commerce deployment troubleshooter in the Commerce Help Center.

On this page