Salesforce Second-Generation Package (2GP) Version Creation Troubleshooting

Step 1: Enabling features and settings

Review the features and settings in project-scratch-def.json:

• Check if all required features on which the package metadata is dependent are enabled (e.g., enableEnhancedNotes, enableLiveAgent, enableOmniChannel)
• Ensure API version compatibility
• Make sure to use right preview flag during release times.

Common Issues to Check:

• Missing features and preferences that metadata depends on
• Incorrect API version settings
• Incompatible feature combinations

Resources:
Scratch Org Features
Metadata Settings
Specifying Salesforce Release

Useful Commands

# Validate scratch org definition
sf org create scratch --definition-file config/project-scratch-def.json --dry-run

# Check org features
sf org display --target-org <scratch-org-alias>

 #creating a pacakge with scratch org def file
sf package version create --package <package alias/ID> --installation-key-bypass -v <target-org>

Step 2: Verifying Package Dependencies

Validate that all package dependencies are correctly defined in the package directory file. Below are the steps to follow:

Review sfdx-project.json:

• Verify all dependencies required for package metadata are listed in dependencies section.
• Check version numbers(ex: 1.0.0.RELEASED) and package IDs (ex: 04txxx).
• Ensure dependency hierarchy is correct

Common Issues to Check:

• Missing package dependencies
• Incorrect version numbers
• Circular dependencies
• Unresolved dependency conflicts

Validation Commands:

# Validate project configuration
sf project validate start

# Check dependency tree
sf project dependency tree

# Resolve dependencies
sf project deploy start --source-dir force-app --dry-run

Resources: 
Create Dependencies Between Second-Generation Managed Packages

Step 3: Verifying Metadata

Validate that metadata can be successfully deployed to the build org without errors. Debugging Actions:

Deploy to Scratch Org, create a scratch org with scratch-org-def file with required features and settings related to metadata and install if we have dependencies:

• Test deployment of entire project/package metadata in a above created scratch org
• Check for any deployment errors/Test class failures.
• Validate metadata structure.

Common Issues to Check:

• Invalid metadata syntax
• Missing required fields
• Permission issues
• Custom object/field conflicts

Validation Commands:
# Deploy with validation only
sf project deploy start --source-dir force-app --dry-run

# Check metadata validity
sf project deploy validate --source-dir force-app

# Deploy to scratch org for testing
sf project deploy start --source-dir force-app --target-org <scratch-org-alias>

Step 4: Package Version Creation Validation

Check Package Configuration:

• Verify sfdx-project.json package configuration
• Ensure proper package type (Managed/Unlocked)
• Validate package naming conventions

Build Process Validation without code coverage to validate if required metadata is valid:

   # Create package version with validation
   sf package version create --package <package-alias> --installation-key-bypass --wait 10
   
   # Check build status
   sf package version report --package-version-id <version-id>