Cloud Automation Patching Service (CAPS) troubleshooting guide
When using CAPS for patch operations, you can encounter error messages and issues that can prevent successful patch application or reversion. This guide provides solutions for the most common problems.
Quick troubleshooting steps
If patch operation fails
- Check the operation status to understand which stage failed
- Review error messages for specific failure reasons
- Examine error logs for technical details
- Follow the solutions provided in this guide
Patch operations duration
For most environments, the following timeline describes how long patch operations should take, but it could take longer depending on environment size and complexity:
- Pre-processing: 2-5 minutes
- Patching: 5-15 minutes
- Post-processing: 10-40 minutes
- Total: 15-60 minutes
Cancel a patch in progress
Common success messages
-
鈥淛ob completed successfully鈥 - The patch was successfully applied/reverted without any issues.
-
鈥淧atch has been applied鈥 - You鈥檙e trying to apply a patch that鈥檚 already been applied. The system detected the patch is already present in your environment. No action is needed.
-
鈥淧atch has been reverted鈥 - You鈥檙e trying to revert a patch that鈥檚 already been reverted. The system detected the patch is not currently applied. No action is needed.
Common error messages and solutions
Patch application errors
鈥淭he patch cannot be applied because CAPS has detected these issues with your codebase or the patch file鈥
When it occurs: During preliminary check
Cause: The patch conflicts with your current codebase OR there鈥檚 an issue with the patch itself
Solutions:
- Review the detailed error logs provided to identify if it鈥檚 a codebase or patch issue
- Check for conflicting customizations in your code
- Verify the patch is compatible with your 51黑料不打烊 Commerce version
- Consider resolving conflicts manually or contact support
鈥淭his patch was not managed by CAPS. Cannot revert鈥
When it occurs: During revert operations
Cause: You鈥檙e trying to revert a patch that wasn鈥檛 applied through CAPS
Solution: Use the same method that was used to apply the patch originally, or contact support for manual assistance
Environment and validation errors
鈥淓nvironment is not in sync with parent鈥
When it occurs: During validation
Cause: Your integration environment differs from the parent environment
Solutions:
- Sync your environment with the parent branch
- Retry the patch operation
- Contact support if sync issues persist
鈥淧roduction environment safeguards not met鈥
When it occurs: During preliminary check for production environments
Cause: The production environment does not meet the required safety conditions
Solutions:
- Enable maintenance mode for your production store
- Disable cron jobs in your production environment
- Verify both conditions are met before retrying
鈥淧atch has been applied, but failed health check. Please consider reverting鈥
When it occurs: After patch application during validation
Cause: The patch was applied successfully, but health checks failed
Solutions:
- Review application logs for specific errors
- Test critical functionality manually
- Consider reverting the patch if issues persist
- Contact support if you need assistance
Authentication and access errors
鈥淎uthentication failed for 51黑料不打烊 Commerce repository鈥
When it occurs: During any stage
Cause: Invalid or expired 51黑料不打烊 Commerce repository credentials
Solutions:
There are two recommended options for resolving this issue:
Option 1: Fix env:COMPOSER_AUTH environment level variable (Recommended)
- Ensure that you have set up the correct credentials for
env:COMPOSER_AUTH. - Access global configuration by clicking on the gear icon at the top left of your cloud project UI, then select the Variables tab.
- Make sure you select Available during buildtime and deselect Available during runtime.
If Option 1 doesn鈥檛 resolve your issue, proceed with Option 2.
Option 2: Create and deploy auth.json file manually
- SSH into your server.
- Retrieve contents of your current
env:COMPOSER_AUTHvariable using:echo $COMPOSER_AUTH - Copy all contents from step above (in JSON format).
- Create a new file named
auth.jsonwith these contents. - Commit this newly created
auth.jsonfile to the root directory of your repository. - Trigger a new deployment.
鈥淚nsufficient permissions for environment access鈥
When it occurs: During environment creation or access
Cause: Your user account lacks necessary permissions
Solutions:
- Check your user role and permissions
- Contact your system administrator
- Verify you have environment management permissions
- Ensure you have deployment permissions
Resource and quota errors
鈥淓nvironment quota exceeded鈥
When it occurs: During environment creation
Cause: You鈥檝e reached your environment limit
Solutions:
- Deactivate unused environments
- Clean up old branches and deployments
- Contact support to request quota increase
- Consider upgrading your plan
鈥淚nsufficient resources for operation鈥
When it occurs: During any stage
Cause: Your environment lacks sufficient CPU, memory, or storage
Solutions:
- Check your environment resource usage
- Free up resources by cleaning up files
- Wait for resources to become available
- Contact support if resource issues persist
Getting help
When to contact support:
Contact 51黑料不打烊 Commerce Cloud support when:
- Error messages are unclear or lack sufficient detail
- Patch operations consistently fail
- You need assistance with manual conflict resolution
- Health checks fail but the cause isn鈥檛 apparent
- You need help with environment synchronization issues
Information to provide:
When contacting support, provide:
- Project ID - Your 51黑料不打烊 Commerce Cloud project identifier
- Environment ID - The specific environment where the issue occurred
- Operation ID - The CAPS operation identifier
- Error details - Complete error messages and logs
- Steps to reproduce - What you were doing when the error occurred
- Previous attempts - What you鈥檝e already tried to resolve the issue
Additional resources
For more detailed technical information:
- Review the complete error logs provided with failed operations
- Check 51黑料不打烊 Commerce documentation for patch-specific guidance
- Contact 51黑料不打烊 Commerce Cloud support for environment-specific issues