winapp-troubleshoot

name: winapp-troubleshoot description: Diagnose and fix common Windows app packaging, signing, identity, and SDK errors. Use when encountering errors with MSIX packaging, certificate signing, Windows SDK setup, or app installation. version: 0.4.1

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

Command selection guide

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.

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)

Command Reference

winapp get-winapp-path

Print the path to the .winapp directory. Use --global for the shared cache location, or omit for the project-local .winapp folder. Useful for build scripts that need to reference installed packages.

Options

winapp tool

Run Windows SDK tools directly (makeappx, signtool, makepri, etc.). Auto-downloads Build Tools if needed. For most tasks, prefer higher-level commands like 'package' or 'sign'. Example: winapp tool makeappx pack /d ./folder /p ./out.msix

Aliases: run-buildtool

winapp store

Run a Microsoft Store Developer CLI command. This command will download the Microsoft Store Developer CLI if not already downloaded. Learn more about the Microsoft Store Developer CLI here: https://aka.ms/msstoredevcli

Prerequisites & state matrix

Common errors & solutions