Introduction:

This article is in regards to Troubleshooting and Resolving Configuration Migration Package Deployment Errors.

Troubleshooting and Resolving Package Deployment Errors

Most of all deployment errors can be avoided by executing dry runs to validate the deployment process and reviewing the validation log and package component comparison. When Vault encounters an error during deployment, it stops the deployment but does not roll back any configuration changes it already made.

If deployment issues are encountered, it is likely due to missing dependencies on components or data. If deploying multiple packages, check the dependencies that exist between those packages and import & deploy the package with the missing dependency first. 

To resolve errors and complete deployment, follow the steps below.

Note:  Review the deployment log to understand what caused the error. Identify the deployment step that caused the error and review the error code and message.

1. If the issue to resolve is in the source Vault: Complete the configuration change in the source Vault and re-export the VPK file. Restart the deployment process with the updated package. These issues are likely to be missing dependencies that are not included in the outbound package. Add these dependencies and re-export your VPK file.  
   
   
2. If the issue to resolve is in the target Vault: Complete the data update or configuration update and go back to the inbound package with the error and restart the deployment process. Previously deployed steps automatically are skipped. These issues are likely to be due to data updates, settings, or configuration changes that need to be made in the target Vault to enable the incoming configuration update. These should be manual steps in the deployment process that should be planned for in the deployment checklist.
   
   
3. If the issue to resolve is in another package due to a missing dependency: Import and deploy the package with the missing dependency first. Then, re-validate the inbound package with the error and restart the deployment process.
   
   
4. Maintain and update the deployment checklist with these steps.

Having a basic understanding of Components and MDL helps troubleshoot issues faster.

Reference:

• Component Types
• MDL Overview
  
  

Error Code Definition:

Error codes are generated for every component step that is deployed. They can be found in the validation and deployment logs for inbound packages.

Example:  An error code and its format.  GEN-FREC-II-1025

Error codes with GEN F II as the component type, response, and category are typically due to missing dependencies. Review what values are invalid or missing in the target Vault and add them to the package.  Re-export the VPK file.

Reference: 

• Configuration Migration Errors & Warnings

Special behavior in Configuration Migration Deployments:

• Details for Document Field Migration
• Details for Document Lifecycle Migration
• Details for Document Workflow Migration
• Details for Object Type Migration
  • If changing the default Objecttype to a new one, it is necessary to deploy the new Objecttype first. If the Object does not have Type enabled, create a VPK to first enable Type, then deploy Objecttype before setting a new default Objecttype.
• Details for Object Lifecycle Migration
• Details for Object Workflow Migration
  • When workflows are migrated, they are inactive in the target Vault. They need to be activated when the deployment is completed.
• Details for Saved View Migration
• More on Searchable Field Migration
  • Searchablefield is auto-provisioned with Objects. They do not need to be included in a Migration Package unless they are manually created
• More on Job Migration
  • When jobs are migrated, they are inactive in the target Vault. They need to be activated when the deployment is complete.
• Component Deployment Order
• Component Types

Related Documentation: