Troubleshooting Guide

This guide helps resolve common issues with PPDS ALM workflows and actions.

Authentication Errors

"AADSTS700016: Application not found"

Cause: The Client ID doesn't match any app registration in the specified tenant.

Solution:

1. Verify the Client ID is correct
2. Ensure the app registration is in the same tenant
3. Check for typos in the Client ID
4. Verify you're using ${{ vars.POWERPLATFORM_CLIENT_ID }} (variable, not secret)

"AADSTS7000215: Invalid client secret"

Cause: The client secret is incorrect or expired.

Solution:

1. Verify you're using the secret value, not the secret ID
2. Check if the secret has expired in Azure AD
3. Create a new client secret if needed
4. Update your GitHub Secret: POWERPLATFORM_CLIENT_SECRET

"The user is not a member of the organization"

Cause: No application user exists in Dataverse for this app registration.

Solution:

1. Go to Power Platform Admin Center
2. Select your environment
3. Go to Settings > Users + permissions > Application users
4. Create an application user for your app registration
5. Assign appropriate security roles (System Administrator for full access)

"Insufficient privileges"

Cause: The application user lacks required permissions.

Solution:

1. Check the security roles assigned to the application user
2. For solution operations, ensure the role has:
   • Solution: Create, Read, Write, Delete
   • Plugin assemblies (if deploying plugins)
   • Customization: Publish All
3. Consider using System Administrator for troubleshooting

Import Errors

Import Skipped (Version Match)

Symptom: Workflow shows "Import skipped - target environment has same or newer version"

Cause: This is expected behavior when skip-if-same-version: true (default).

Solution (if you want to force import):

- uses: joshsmithxrm/ppds-alm/.github/actions/import-solution@v1
  with:
    solution-path: ./MySolution_managed.zip
    skip-if-same-version: 'false'

"Cannot start another solution at the same time"

Cause: Another import is in progress in the same environment.

Default Behavior: The import action automatically retries up to 3 times with 5-minute delays.

If retries fail:

1. Check if another pipeline is running against the same environment
2. Check Power Platform Admin Center for stuck import jobs
3. Wait for the other import to complete
4. Increase retry settings if needed:

with:
  max-retries: '5'
  retry-delay-seconds: '600'  # 10 minutes

"Solution import failed" (General)

Cause: Various - missing dependencies, version conflicts, etc.

Solution:

1. Check the workflow logs for specific error messages
2. Check Power Platform Admin Center > Environments > History > Solution History
3. Common issues:
   • Missing dependencies: Install required solutions first
   • Version conflict: Ensure source version > target version, or disable version check
   • Component conflict: Check for customizations blocking import

"Missing dependency" errors

Cause: The solution references components from other solutions not installed in target.

Solution:

1. Identify the missing component from the error message
2. Install the required base solution first
3. Consider using solution layering properly
4. Check if a publisher prefix is missing

Export Errors

"Solution not found"

Cause: The solution unique name doesn't match.

Solution:

1. Verify the solution unique name (not display name)
2. Check for case sensitivity
3. Ensure the solution exists in the source environment
4. Use pac solution list to see available solutions

PAC CLI --allowDelete not working (Linux)

Symptom: Removed components remain in repository after export.

Cause: Known PAC CLI bug on Linux runners.

Solution: PPDS ALM includes automatic workaround:

• The export-solution action deletes the solution folder before unpack
• Removed components are properly deleted
• If unpack fails, the folder is restored from git

Export produces no changes

Cause: May be due to noise filtering (if enabled) or no actual changes.

Solution:

1. Check if filter-noise: true is set
2. Review the analyze-changes output to see what was filtered
3. To see all changes regardless:

with:
  filter-noise: false

Build Errors

".NET solution file not found"

Cause: The build action couldn't locate a .sln file.

Solution:

- uses: joshsmithxrm/ppds-alm/.github/actions/build-solution@v1
  with:
    solution-path: ./src/MySolution.sln

Plugin assembly not found after build

Cause: Build output location doesn't match expected conventions.

Solution:

1. Check the plugins-folder input matches your project structure
2. Verify build output exists in bin/Release (or specified configuration)
3. Check that build succeeded (review logs)

Copy plugin assemblies failed

Symptom: "No folder matching pattern found in PluginAssemblies"

Cause: The solution folder doesn't have the expected plugin assembly folder structure.

Solution:

1. Ensure the solution was exported with plugins registered
2. Check that PluginAssemblies/{AssemblyName}-{GUID}/ folder exists
3. Verify the assembly name pattern matches (dots are removed):
   • Build output: MyProject.Plugins.dll
   • Expected folder: MyProjectPlugins-{GUID}/

Solution Checker Errors

"Solution Checker failed"

Cause: Solution has issues exceeding the configured threshold.

Solution:

1. Review the checker output in the workflow summary
2. Download the SARIF results file from artifacts
3. Address issues based on severity
4. Adjust threshold if needed:

with:
  fail-on-level: Critical  # Only fail on critical issues

"Geography not supported"

Cause: Invalid geography specified for Solution Checker.

Solution: Use a valid geography:

• unitedstates (default)
• europe
• asia
• australia
• japan
• india
• canada
• southamerica

GitHub Actions Specific

"Cannot find reusable workflow"

Cause: Incorrect workflow reference.

Solution:

1. Verify the repository path: joshsmithxrm/ppds-alm
2. Check the workflow path uses the standard .github/workflows/ prefix:

   # Correct
   uses: joshsmithxrm/ppds-alm/.github/workflows/solution-deploy.yml@v1

3. Ensure you're using a valid ref (@v1, @main, etc.)

"Resource not accessible by integration"

Cause: GitHub token lacks required permissions.

Solution:

permissions:
  contents: read
  actions: read

Environment variables not found

Symptom: ${{ vars.POWERPLATFORM_ENVIRONMENT_URL }} is empty

Cause: Variables not configured in GitHub Environment.

Solution:

1. Go to Settings > Environments > [Your Environment]
2. Add required variables
3. Ensure workflow specifies the environment:

jobs:
  deploy:
    environment: QA  # Must match your environment name

Debug Mode

Enable Verbose Logging

GitHub Actions:

env:
  ACTIONS_STEP_DEBUG: true

For specific actions:

- uses: joshsmithxrm/ppds-alm/.github/actions/analyze-changes@v1
  with:
    solution-folder: solutions/MySolution/src
    debug: 'true'

Getting Help

Collect Information

When reporting issues, include:

1. Environment details: Runner OS, PAC CLI version, .NET version
2. Error details: Full error message, workflow step that failed
3. Configuration: Workflow YAML (sanitize secrets!)

Support

• GitHub Issues: ppds-alm Issues

FAQ

Q: Can I use these templates with on-premises Dataverse? A: These templates are designed for Dataverse Online. On-premises would require authentication changes.

Q: Why is my import being skipped? A: Version comparison is enabled by default. Set skip-if-same-version: false to always import.