winapp-troubleshoot

If you can't run winapp yourself (no shell, or the command is denied), give the user the exact winapp command(s) for their project instead of only describing the steps.

When to use

Use this skill when:

• Diagnosing errors from winapp CLI commands
• Choosing the right command for a task
• Understanding prerequisites — what each command needs and what it produces

Common errors & solutions

For slow WinUI layout or scrolling, use the winapp-performance skill. ETW performance capture is separate from debugger output and crash analysis.

For --unique-identity errors about unsupported extensions or resources, see unique identity for parallel checkouts. Run without the flag instead of working around the check.

Command selection guide

Is the app a single .cs file (.NET file-based app)?
├─ Yes → winapp run <file>.cs  (builds it and generates the manifest for you)
└─ No → Does the project have a Package.appxmanifest?
   ├─ No → Do you want full setup (manifest + config + optional SDKs)?
   │       ├─ Yes → winapp init (adds Windows platform files to existing project)
   │       └─ No, just a manifest → winapp manifest generate
   └─ Yes
      ├─ Has winapp.yaml, cloned/pulled but .winapp/ folder missing?
      │  └─ winapp restore
      ├─ Want newer SDK versions?
      │  └─ winapp update
      ├─ Need a dev certificate?
      │  └─ winapp cert generate (then winapp cert install for trust)
      ├─ Need package identity for debugging? (see [Debugging Guide](https://github.com/microsoft/WinAppCli/blob/main/docs/debugging.md))
      │  ├─ Exe is in your build output folder? (most frameworks)
      │  │  └─ winapp run <build-output-dir>
      │  └─ Exe is separate from app code? (Electron, sparse testing)
      │     └─ winapp create-debug-identity <exe>
      ├─ Ready to create MSIX installer?
      │  └─ winapp package <build-output> --cert ./devcert.pfx
      ├─ Need to sign an existing file?
      │  └─ winapp sign <file> <cert>
      ├─ Need to update app icons?
      │  └─ winapp manifest update-assets ./logo.png
      ├─ Need to run SDK tools directly?
      │  └─ winapp tool <toolname> <args>
      ├─ Need to publish to Microsoft Store?
      │  └─ winapp store <args> (passthrough to Store Developer CLI)
      └─ Need the .winapp directory path for build scripts?
         └─ winapp get-winapp-path (or --global for shared cache)

Important notes:

• winapp init adds files to an existing project — it does not create a new project
• The key prerequisite for most commands is Package.appxmanifest, not winapp.yaml
• winapp.yaml is only needed for SDK version management (restore/update)
• Projects with NuGet package references (e.g., .csproj referencing Microsoft.Windows.SDK.BuildTools) can use winapp commands without winapp.yaml
• For Electron projects, use the npm package (npm install --save-dev @microsoft/winappcli) which includes Node.js-specific commands under npx winapp node

Debugging approach quick reference

Visual Studio users: If you have a packaging project, VS already handles identity and debugging from F5 — you likely don't need winapp for debugging. These workflows are for VS Code, terminal, and frameworks VS doesn't natively package.

For full details, see the Debugging Guide.

Prerequisites & state matrix

Debugging tips

• Add --verbose (or -v) to any command for detailed output
• Add --quiet (or -q) to suppress progress messages (useful in CI/CD)
• Run winapp --cli-schema to get the full JSON schema of all commands and options
• Run any command with --help for its specific usage information
• Use winapp get-winapp-path to find where packages are stored locally
• Use winapp get-winapp-path --global to find the shared cache location

Getting more help

• Full CLI documentation: https://github.com/microsoft/WinAppCli/blob/main/docs/usage.md
• Framework-specific guides: https://github.com/microsoft/WinAppCli/tree/main/docs/guides
• File an issue: https://github.com/microsoft/WinAppCli/issues

Related skills

• Setup & init: winapp-setup — adding Windows support to a project
• Manifest: winapp-manifest — creating and editing Package.appxmanifest
• Signing: winapp-signing — certificate generation and management
• Packaging: winapp-package — creating MSIX installers
• Identity: winapp-identity — enabling package identity for Windows APIs
• Frameworks: winapp-frameworks — framework-specific guidance (Electron, .NET, C++, Rust, Flutter, Tauri)
• MAUI: winapp-maui — packaging/signing .NET MAUI Windows apps and resolving the resizetizer manifest

CLI reference

Run winapp <command> --help for current command options, or winapp --cli-schema for the complete machine-readable command schema.