winapp-troubleshoot
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 |
More from microsoft/winappcli
winapp-package
Package a Windows app as an MSIX installer for distribution or testing. Use when creating a Windows installer, packaging an Electron/Flutter/.NET/Rust/C++/Tauri app for Windows, building an MSIX, distributing a desktop app, packaging a console app or CLI tool, or adding MSIX packaging to a build script or CI/CD pipeline.
5winapp-setup
Set up a Windows app project for MSIX packaging, Windows SDK access, or Windows API usage. Use when adding Windows support to an Electron, .NET, C++, Rust, Flutter, or Tauri project, or restoring SDK packages after cloning.
5winapp-identity
Enable Windows package identity for desktop apps to access Windows APIs like push notifications, background tasks, share target, and startup tasks. Use when adding Windows notifications, background tasks, or other identity-requiring Windows features to a desktop app.
5winapp-frameworks
Framework-specific Windows development guidance for Electron, .NET (WPF, WinForms), C++, Rust, Flutter, and Tauri. Use when packaging or adding Windows features to an Electron app, .NET desktop app, Flutter app, Tauri app, Rust app, or C++ app.
5winapp-signing
Create and manage code signing certificates for Windows apps and MSIX packages. Use when generating a certificate, signing a Windows app or installer, or fixing certificate trust issues.
4winapp-manifest
Create and edit Windows app manifest files (appxmanifest.xml) that define app identity, capabilities, and visual assets, or generate new assets from existing images. Use when creating a Windows app manifest for any app type (GUI, console, CLI tool, service), adding Windows capabilities, generating new app icons and assets, or adding execution aliases, file associations, protocol handlers, or other app extensions.
4