Skip to main content
skill CX Codex

diagnose-deployment — Claude Code skill: deployment errors

diagnose-deployment is a Claude Code skill that finds Power Pages upload and Dataverse solution import errors. Run it to investigate a failed deployment or ask for fixes to detected issues.

MIT ★ 1,167 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add microsoft/power-platform-skills
/plugin install power-pages@power-platform-skills
Open on GitHub

What diagnose-deployment does

The skill reruns pac pages upload-code-site, captures PAC CLI output, and matches errors against a catalog of known failures. It checks project artifacts, including powerpages.config.json, and can query Dataverse for solution import status. The upload command runs again on purpose so the skill can collect current errors.

The project root must contain powerpages.config.json, and PAC CLI must be installed. Azure CLI is used to query import status; the skill skips that check when authentication is unavailable. It can consult Microsoft Learn through MCP, then continue if the documentation search or fetch fails.

Before each available fix, the skill asks for separate approval. It makes no changes without confirmation.

What it helps with

  • find PAC CLI errors from a site upload
  • check failed solution imports in Dataverse
  • spot missing project artifacts or an empty build
  • match deployment failures to known error patterns
  • apply a proposed fix after approval

Example prompts for the agent

  • Find out why my Power Pages deployment failed.
  • Show the upload errors and check the solution import.
  • Diagnose the deployment and suggest fixes.

How to install diagnose-deployment

1Plugin marketplace

/plugin marketplace add microsoft/power-platform-skills
/plugin install power-pages@power-platform-skills

This installs the whole power-pages plugin with all its skills

2Skills CLI (Vercel)

npx skills add microsoft/power-platform-skills --skill diagnose-deployment -a claude-code

3Manually: put the files in place

~/.claude/skills/diagnose-deployment/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/diagnose-deployment/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about diagnose-deployment

What does diagnose-deployment do?

It collects upload and import errors, matches them against known issues, and offers available fixes. Each fix requires separate approval.

What does diagnose-deployment need to run?

The project root needs powerpages.config.json, and PAC CLI must be installed. Azure CLI is needed to check solution import status.

Source text

SKILL.md · MIT
---
name: diagnose-deployment
description: >-
  Surfaces PAC CLI upload errors and Dataverse async operation errors, pattern-matches
  against a known failure catalog, and optionally auto-fixes identified issues. Use when
  asked to: "diagnose deployment", "debug deployment", "deployment failed", "show
  deployment errors", "fix deployment issues", "show upload logs", "why did my deploy fail",
  or "troubleshoot upload".
user-invocable: true
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskUpdate, TaskList, AskUserQuestion, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search, mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch
model: opus
---

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

# diagnose-deployment

Surfaces and pattern-matches deployment errors against a known failure catalog. For each identified error with an available auto-fix, asks explicit user permission before applying any changes. Never auto-applies fixes without confirmation.

## Prerequisites

- Project root with `powerpages.config.json`
- PAC CLI installed (will report if missing)

## Phases

### Phase 1 — Verify Prerequisites and Locate Project

**Create all tasks upfront at the start of this phase.**

Tasks to create:
1. "Verify prerequisites and locate project"
2. "Collect deployment artifacts"
3. "Surface upload errors"
4. "Query solution import status"
5. "Diagnose and categorize findings"
6. "Offer auto-fixes"
7. "Present findings summary"

Steps:
1. Locate project root: search for `powerpages.config.json` in cwd and parent directories
2. Check PAC CLI: `pac --version` (report version or "not installed")
3. Check PAC CLI auth: `pac env who` (report environment URL or "not authenticated")
4. Check Azure CLI: `az account show` (report subscription or "not logged in")

Auth failures are non-blocking — report them as findings, continue collecting other artifacts.

### Phase 1.5 — Ground in current ALM documentation

> Reference: `${PLUGIN_ROOT}/references/alm-docs-grounding.md`

Cap this step at ~30 seconds. If MCP search / fetch errors out, log a one-line note and continue — this skill must remain runnable offline.

1. Run `microsoft_docs_search` with the query: `Power Pages deployment errors solution import troubleshooting`.
2. Fetch `https://learn.microsoft.com/en-us/power-platform/alm/solution-concepts-alm` (and at most one sister page on troubleshooting or known import errors) in parallel via `microsoft_docs_fetch`.
3. Extract a one-paragraph summary of what Microsoft Learn currently says about common deployment failures and their resolution. Compare against `${PLUGIN_ROOT}/references/deployment-error-catalog.md` and flag any new error patterns not yet captured in the catalog.
4. Use the summary to inform pattern-matching in Phase 5. If a new pattern is documented on Learn that isn't in the catalog, surface it to the user as a candidate addition rather than silently extending the catalog.

### Phase 2 — Collect Deployment Artifacts

Gather all available context:

1. Read `powerpages.config.json` — extract `siteName`, `websiteRecordId`, `compiledPath`
2. Check `.powerpages-site/` folder exists
3. Glob for manifest files: `.powerpages-site/*-manifest.yml` — list all found, note their environment hostnames
4. Check if `.solution-manifest.json` exists (for solution-related diagnostics)
5. Check if `docs/alm/last-import.json` exists (for recent import failures)
6. Check build output: confirm `{compiledPath}/` exists and is non-empty

Report: "Found project: `{siteName}`. Artifacts collected."

### Phase 3 — Surface Upload Errors

Re-run `pac pages upload-code-site` in capture mode to get fresh error output:

```bash
pac pages upload-code-site --rootPath "." 2>&1
```

> **Note**: This intentionally triggers the upload to capture any errors. If the upload succeeds cleanly, that is also a valid diagnostic result ("no errors found").

Capture stdout+stderr as a single string. Pass to `scripts/parse-deployment-errors.js`:

```bash
echo "{escaped-output}" | node "${PLUGIN_ROOT}/scripts/parse-deployment-errors.js"
```

Parse the JSON findings array. If the upload succeeded with no errors, note this and skip to Phase 5 with an empty findings list.

### Phase 4 — Query Solution Import Status

Only run if `.solution-manifest.json` exists.

1. Acquire Azure CLI token for environment URL
2. Check recent async operations (last 24 hours):
   ```
   GET {envUrl}/api/data/v9.2/asyncoperations?$filter=statecode eq 3 and statuscode eq 31 and createdon gt {yesterday}&$select=asyncoperationid,name,message,friendlymessage,statuscode,completedon&$orderby=completedon desc&$top=5
   ```
3. Check recent import jobs:
   ```
   GET {envUrl}/api/data/v9.2/importjobs?$select=solutionname,completedon,progress&$orderby=completedon desc&$top=3
   ```
4. If failed operations found, pass each `message` field through `parse-deployment-errors.js`

Skip gracefully if auth is not available (auth failure in Phase 1).

### Phase 5 — Auto-Diagnose Known Issues

Consolidate all findings from Phases 3 and 4. For each finding, categorize:

- **Error**: Blocks deployment
- **Warning**: May cause issues
- **Info**: Informational

Also add findings for missing artifacts discovered in Phase 2:
- Missing `websiteRecordId` → Error (patternId: `missing-website-record-id`)
- Empty build output → Error (patternId: `empty-build`)
- Multiple environment manifests → Warning (may indicate environment confusion)

Present all findings in a table:

| # | Severity | Type | Issue | Auto-fix? |
|---|---|---|---|---|
| 1 | Error | upload | JavaScript uploads blocked | Yes |
| 2 | Warning | config | Multiple manifest files found | No |

### Phase 6 — Offer Auto-Fixes

For each Error finding with `autoFixAvailable: true`, in order:

<!-- gate: diagnose-deployment:6.auto-fix | category=consent | cancel-leaves=nothing -->
> 🚦 **Gate (consent · diagnose-deployment:6.auto-fix):** Per-finding consent before applying any auto-fix. **Loops once per Error finding with `autoFixAvailable: true`** — each finding gets its own Yes / No / Skip-all `AskUserQuestion`. The pattern ID surfaces in the prompt. **Never batch fixes** — three findings = three separate consent prompts (unless the user picks "Skip all" on the first, which short-circuits the loop). The Yes from finding 1 does NOT cover finding 2; each fix has its own blast radius (different files, different settings, different reversibility).

1. Explain the issue and proposed fix
2. Ask explicit permission via `AskUserQuestion`:
   > "Issue: {message}
   > Proposed fix: {suggestedFix}
   > Apply this fix? Yes / No / Skip all auto-fixes"

3. If approved, execute the fix:

   **`stale-manifest`**: Delete `*-manifest.yml` file(s) in `.powerpages-site/`
   ```bash
   # Ask which manifest to delete if multiple found, then:
   rm ".powerpages-site/{manifestFile}"
   ```

   **`blocked-js`**: Update `blockedattachments` setting
   ```bash
   # Get current setting first
   pac env list-settings | grep -i blocked
   # Remove .js from the blocked list (preserve other blocked types)
   pac env update-settings --name blockedattachments --value "{updated-value}"
   ```

   **`missing-website-record-id`**: Retrieve and update record ID
   ```bash
   pac pages list
   # Parse output, find matching site by name, then update powerpages.config.json
   ```

   **`auth-expired`**: Guide re-authentication
   ```bash
   pac auth create --environment "{envUrl}"
   az login
   ```

   **`empty-build`**: Run build
   ```bash
   npm run build
   ```

4. After each fix, re-run the relevant check to verify it resolved the issue. Update finding status to "Fixed" or "Manual required".

> **Key Constraint**: Never apply any fix without explicit user permission. Each fix requires a separate confirmation.

### Phase 7 — Present Findings Summary

Display a final summary table of all findings:

| # | Severity | Type | Issue | Status |
|---|---|---|---|---|
| 1 | Error | upload | JS uploads blocked | Fixed |
| 2 | Error | config | Missing websiteRecordId | Manual required |
| 3 | Warning | config | Multiple manifest files | Informational |

**Status values**:
- **Fixed**: Auto-fix was applied and verified
- **Manual required**: No auto-fix available — show manual steps
- **Skipped**: User declined the fix
- **Informational**: Warning/Info, no action needed

If all errors are resolved: suggest retrying deployment with `/power-pages:deploy-site`.

If manual steps remain: list them explicitly with commands or links.

### Record Skill Usage

> Reference: `${PLUGIN_ROOT}/references/skill-tracking-reference.md`

Follow the skill tracking instructions in the reference to record this skill's usage. Use `--skillName "DiagnoseDeployment"`.

## Key Decision Points (Wait for User)

1. **Phase 6**: Each individual auto-fix requires explicit confirmation before applying
2. **Phase 6**: If user says "Skip all auto-fixes", stop offering fixes and go to summary

## Error Handling

- If `pac pages upload-code-site` produces no output: report "No upload errors detected in current state"
- If Azure CLI token unavailable: skip Phase 4, note in summary
- If `parse-deployment-errors.js` returns no findings: report "No known error patterns detected" and show raw output for manual review

## Progress Tracking Table

| Task subject | activeForm | Description |
|---|---|---|
| Verify prerequisites and locate project | Verifying prerequisites | Check PAC CLI, Azure CLI, locate project root and powerpages.config.json |
| Collect deployment artifacts | Collecting deployment artifacts | Read config, list manifests, check build output, check solution manifest |
| Surface upload errors | Surfacing upload errors | Re-run pac pages upload-code-site in capture mode, parse stdout/stderr |
| Query solution import status | Querying solution import status | Check recent failed async operations and import jobs in Dataverse |
| Diagnose and categorize findings | Diagnosing findings | Pattern-match all errors against deployment-error-catalog, assign severity |
| Offer auto-fixes | Applying auto-fixes | For each fixable error, ask permission and execute fix, verify result |
| Present findings summary | Presenting summary | Show all findings table with severity and fix status, list manual steps |

© Microsoft · MIT · microsoft/power-platform-skills

Similar skills

All skills for DevOps and infrastructure →

From the same set157

The whole set →
add-pen-input The add-pen-input skill creates or checks a wrapper for handwriting and signature capture in a mobile app. /add-native routes pen, ink, drawing, and handwriting requests to it. CX Codex +1 ★ 1,167repo stars canvas-app-planner canvas-app-planner is a Microsoft subagent for Claude Code that turns approved Canvas App edits into implementation contracts for each screen while preserving existing logic and layout. CX Codex ★ 1,167repo stars assemble-ppmplugin assemble-ppmplugin is a Claude Code skill that assembles a .ppmplugin bundle from a manifest and Android/iOS binaries, validates them, and packages the result. It runs after /generate-ppmplugin-manifest and build skills. CX Codex +1 ★ 1,167repo stars add-geolocation The add-geolocation skill sets up background GPS tracking with durable storage and Dataverse sync in a mobile app. The /add-native geolocation command invokes it. CX Codex +1 ★ 1,167repo stars assign-offline-profile assign-offline-profile binds users and teams to a Dataverse Mobile Offline Profile so mobile apps can download and sync offline records. CX Codex +1 ★ 1,167repo stars canvas-app Create or revise a Power Apps Canvas App with Canvas Authoring MCP. The skill covers screen changes, responsive layouts, and compile-error fixes. CX Codex +1 ★ 1,167repo stars set-app-registration-native set-app-registration-native wires a Power Apps Wrap mobile app to an Entra ID app registration by writing auth.config.json. Discovers existing registrations in the tenant and checks API permissions. CX Codex +1 ★ 1,167repo stars preview-screens preview-screens generates a standalone HTML preview of mobile screens inside a 375 × 812 phone frame without starting Metro or a simulator. CX Codex +1 ★ 1,167repo stars

Project sponsors

Companies that keep this analytics open