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".
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".
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:
"Verify prerequisites and locate project"
"Collect deployment artifacts"
"Surface upload errors"
"Query solution import status"
"Diagnose and categorize findings"
"Offer auto-fixes"
"Present findings summary"
Steps:
Locate project root: search for powerpages.config.json in cwd and parent directories
Check PAC CLI: pac --version (report version or "not installed")
Check PAC CLI auth: pac env who (report environment URL or "not authenticated")
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.
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.
Run microsoft_docs_search with the query: Power Pages deployment errors solution import troubleshooting.
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.
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.
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.
Re-run pac pages upload-code-site in capture mode to get fresh error output:
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:
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.
Acquire Azure CLI token for environment URL
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
Check recent import jobs:
GET {envUrl}/api/data/v9.2/importjobs?$select=solutionname,completedon,progress&$orderby=completedon desc&$top=3
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:
For each Error finding with autoFixAvailable: true, in order:
🚦 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).
Explain the issue and proposed fix
Ask explicit permission via AskUserQuestion:
"Issue: {message}
Proposed fix: {suggestedFix}
Apply this fix? Yes / No / Skip all auto-fixes"
If approved, execute the fix:
stale-manifest: Delete *-manifest.yml file(s) in .powerpages-site/
# Ask which manifest to delete if multiple found, then:rm".powerpages-site/{manifestFile}"
blocked-js: Update blockedattachments setting
# 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
pac pages list
# Parse output, find matching site by name, then update powerpages.config.json
auth-expired: Guide re-authentication
pac auth create --environment "{envUrl}"
az login
empty-build: Run build
npm run build
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.
