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."
license: "MIT"
---

## 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 |
| `run` / `create-debug-identity` registration error `0x800704EC` | Developer Mode is disabled | Enable it in **Settings → Privacy & security → For developers**, or `Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Name AllowDevelopmentWithoutDevLicense -Value 1`, then retry |
| `run` / `create-debug-identity` registration error `0x80073CFB` | Package already registered with a conflicting identity | Run `winapp unregister` (or `winapp unregister --force` if the package was registered from a different project tree), then retry |

## 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

| 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](https://github.com/microsoft/WinAppCli/blob/main/docs/debugging.md).

## 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-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
<!-- 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