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.3.2
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
| Error | Cause | Solution |
|---|---|---|
| "winapp.yaml not found" | Running restore or update without config | Run winapp init first, or cd to the directory containing winapp.yaml |
| "Package.appxmanifest not found" | Running package, create-debug-identity, or cert generate --manifest | Run winapp init or winapp manifest generate first, or pass --manifest <path> |
| "Publisher mismatch" | Certificate publisher ≠ manifest publisher | Regenerate cert: winapp cert generate --manifest, or edit Package.appxmanifest Identity.Publisher to match |
| "Access denied" / "elevation required" | cert install without admin | Run terminal as Administrator for winapp cert install |
| "Package installation failed" | Cert not trusted, or stale package registration | winapp cert install ./devcert.pfx (admin), then Get-AppxPackage <name> | Remove-AppxPackage |
| "Certificate not trusted" | Dev cert not installed on machine | winapp cert install ./devcert.pfx (admin) |
| "Build tools not found" | First run, tools not yet downloaded | Run winapp update to download tools; ensure internet access |
| "Failed to add package identity" | Stale debug identity or untrusted cert | Get-AppxPackage *yourapp* | Remove-AppxPackage to clean up, then winapp cert install and retry |
| "Certificate file already exists" | devcert.pfx already present | Use winapp cert generate --if-exists overwrite or --if-exists skip |
| "Manifest already exists" | Package.appxmanifest already present | Use winapp manifest generate --if-exists overwrite or edit manifest directly |
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 initadds files to an existing project — it does not create a new project- The key prerequisite for most commands is
Package.appxmanifest, notwinapp.yaml winapp.yamlis only needed for SDK version management (restore/update)- Projects with NuGet package references (e.g.,
.csprojreferencingMicrosoft.Windows.SDK.BuildTools) can use winapp commands withoutwinapp.yaml - For Electron projects, use the npm package (
npm install --save-dev @microsoft/winappcli) which includes Node.js-specific commands undernpx winapp node
Debugging approach quick reference
| Goal | Command | Key detail |
|---|---|---|
| Run with identity (most common) | winapp run .\build\Debug | Registers loose layout + launches; add --with-alias for console apps |
| Attach debugger to running app | winapp run .\build\Debug → attach to PID | Misses startup code |
| Register identity, launch manually | winapp run .\build\Debug --no-launch | Launch via start shell:AppsFolder\<AUMID> or execution alias — not the exe directly |
| F5 startup debugging (IDE launches exe) | winapp create-debug-identity .\bin\myapp.exe | Exe has identity regardless of how it's launched; best for debugging activation/startup code |
| Capture OutputDebugString + crash dump | winapp run .\build\Debug --debug-output | On crash, writes minidump and shows exception type, message, and faulting methods. Blocks other debuggers — use --no-launch if you need VS Code/WinDbg |
| Run and auto-clean | winapp run .\build\Debug --unregister-on-exit | Unregisters the dev package after the app exits |
| Launch and detach (CI) | winapp run .\build\Debug --detach | Returns immediately after launch; use --json to get PID for scripting |
| Clean up stale registration | winapp unregister | Removes dev-mode packages for the current project |
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
| Command | Requires | Creates/Modifies |
|---|---|---|
init | Existing project (any framework) | winapp.yaml, .winapp/, Package.appxmanifest, Assets/, .gitignore update |
restore | winapp.yaml | .winapp/packages/, generated projections |
update | winapp.yaml | Updates versions in winapp.yaml, reinstalls packages |
manifest generate | Nothing | Package.appxmanifest, Assets/ |
manifest update-assets | Package.appxmanifest + source image | Regenerates Assets/ icons |
cert generate | Nothing (or Package.appxmanifest for publisher) | devcert.pfx |
cert install | Certificate file + admin | Machine certificate store |
create-debug-identity | Package.appxmanifest + exe + trusted cert | Registers sparse package with Windows |
run | Build output folder + Package.appxmanifest | Registers loose layout package, launches app |
unregister | Package.appxmanifest (auto-detect or --manifest) | Removes dev-mode package registrations |
package | Build output + Package.appxmanifest | .msix file |
sign | File + certificate | Signed file (in-place) |
create-external-catalog | Directory with executables | CodeIntegrityExternal.cat |
tool <name> | Nothing (auto-downloads tools) | Runs SDK tool directly |
store | Nothing (auto-downloads Store CLI) | Passthrough to Microsoft Store Developer CLI |
get-winapp-path | Nothing | Prints .winapp directory path |
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-schemato get the full JSON schema of all commands and options - Run any command with
--helpfor its specific usage information - Use
winapp get-winapp-pathto find where packages are stored locally - Use
winapp get-winapp-path --globalto 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 editingPackage.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
<!-- auto-generated from cli-schema.json -->| Option | Description | Default |
|---|---|---|
--global | Get the global .winapp directory instead of local | (none) |
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