WinGet Package Validation: Common Failure Labels and How to Fix Them

When you submit a pull request to microsoft/winget-pkgs, automated validation pipelines run a series of checks on your manifest and installers. If something fails, labels are applied to your PR to indicate what went wrong. This document explains each label, what causes it, and how to resolve it.

winget validate <path-to-manifest>
winget install --manifest <path-to-manifest>

Table of Contents

• Status Labels
• Error Labels
  • Manifest & Path Errors
  • Installer & Binary Errors
  • URL & Domain Errors
  • Installation Testing Errors
  • Dependency Errors
  • Other Validation Errors
• Content Policy Labels
• Internal Error Labels
• Moderator-Applied Labels
• Quick Reference Table

Status Labels

These labels track the progress of your PR through the validation pipeline.

Error Labels

Manifest & Path Errors

Manifest-Validation-Error

What it means: Your manifest has a syntax error or does not conform to the manifest schema specification.

Common causes:

• Invalid YAML syntax (bad indentation, missing colons, incorrect types)
• Missing required fields (PackageIdentifier, PackageVersion, PackageName, Publisher, etc.)
• Using a singleton manifest (deprecated in the community repo — use multi-file manifests)

How to fix:

winget validate <path-to-manifest>

Address all reported errors and resubmit.

Manifest-Version-Deprecated

What it means: Your manifest uses a schema version that is no longer accepted by the repository.

How to fix: Update your manifest to use a supported schema version. The recommended schema version is 1.12.0 (1.10.0 is also accepted). Update the ManifestVersion field in all manifest files and ensure the # yaml-language-server: $schema=... comment references the correct version.

Manifest-Path-Error

What it means: Your manifest files are not in the correct directory structure.

Required structure:

manifests/<first-letter>/<Publisher>/<PackageName>/<PackageVersion>/
├── <PackageIdentifier>.installer.yaml
├── <PackageIdentifier>.locale.<language>.yaml
└── <PackageIdentifier>.yaml

Common causes:

• Incorrect casing — PackageIdentifier and directory names are case-sensitive
• Filenames don't match the PackageIdentifier
• Manifest placed outside the manifests/ directory

How to fix: Ensure the directory path and filenames exactly match your PackageIdentifier and PackageVersion.

PullRequest-Error

What it means: The PR itself has structural problems.

Common causes:

• PR contains files outside the manifests/ folder
• PR contains manifests for more than one package or more than one version
• Modified files that are not part of the manifest submission

How to fix: Each PR must contain exactly one package version (one multi-file manifest set). If you need to update non-manifest files such as README.md, files under doc/, spelling files, or tooling, submit those changes in a separate PR. See the first-time contributor checklist before resubmitting.

Manifest-Installer-Validation-Error

What it means: There are inconsistencies or missing values in the manifest discovered during MSIX package evaluation or installer metadata validation.

Common causes:

• InstallerType mismatch between what is declared and what is detected
• Missing or incorrect PackageFamilyName for MSIX packages
• Incorrect MinimumOSVersion for MSIX packages
• Inconsistencies in AppsAndFeaturesEntries

How to fix: Verify that installer metadata matches the actual installer. For MSIX, ensure PackageFamilyName and SignatureSha256 are correct.

Installer & Binary Errors

Binary-Validation-Error

What it means: The installer failed static analysis during the Installers Scan pipeline step. This test runs the installer through multiple antivirus engines.

Common causes:

• Installer flagged as malware or Potentially Unwanted Application (PUA)
• SHA256 hash mismatch between the manifest and the downloaded installer
• Installer URL is inaccessible

How to fix:

1. Verify the InstallerSha256 hash:

   winget hash <path-to-installer>
   

2. If flagged as malware/PUA, submit the installer to Microsoft Defender for analysis as a potential false positive.
3. Ensure the installer URL is publicly accessible.

Error-Hash-Mismatch

What it means: The InstallerSha256 in your manifest does not match the hash of the file downloaded from InstallerUrl.

Common causes:

• The installer was updated at the URL without updating the hash in the manifest
• "Vanity URL" that always points to the latest version — the file changed after you generated the hash
• Copy/paste error in the hash value

How to fix:

winget hash <path-to-installer>

Update the InstallerSha256 value in your manifest and resubmit.

Best practice: Use version-specific URLs rather than vanity URLs to avoid hash mismatches.

Validation-Hash-Verification-Failed

What it means: Similar to Error-Hash-Mismatch, but detected during installation testing. The installer at the URL changed between initial validation and installation testing.

How to fix: Same as Error-Hash-Mismatch — update the hash and use a stable, version-specific URL.

Error-Installer-Availability

What it means: The validation service could not download the installer.

Common causes:

• The InstallerUrl is incorrect or broken
• The hosting server blocks Azure IP ranges
• The server requires authentication or specific headers

How to fix: Verify the URL is correct and publicly accessible. If the URL works from your machine but not in validation, add a comment to your PR — a WinGet engineer will investigate.

URL & Domain Errors

URL-Validation-Error

What it means: A URL in the manifest failed validation. This can be triggered by Microsoft Defender SmartScreen reputation checks or HTTP error responses (403, 404).

Common causes:

• Installer URL returns 404 (file not found) or 403 (forbidden)
• URL has a poor SmartScreen reputation
• URL points to a site flagged for malicious content

How to fix:

1. Check that all URLs in the manifest are valid and accessible.
2. If the issue is reputation-based, submit the URL for review.
3. Look at the PR check details to identify which specific URL failed.

Validation-HTTP-Error

What it means: The InstallerUrl does not use HTTPS.

How to fix: Update the InstallerUrl to use https:// instead of http://.

Validation-Domain

What it means: The domain of the InstallerUrl does not match the expected domain for this publisher. WinGet policy requires that installers come directly from the publisher's release location.

Common causes:

• Using a third-party CDN, mirror, or download aggregator instead of the official publisher URL
• Using a URL shortener or redirector

How to fix: Use the official download URL from the publisher's website. If the URL is legitimate, add a comment to your PR for investigation.

Validation-Unapproved-URL

What it means: Similar to Validation-Domain — the InstallerUrl domain is not an approved source for this publisher.

How to fix: Use the direct URL from the publisher's official release location.

Validation-Indirect-URL

What it means: The installer URL uses a redirect rather than pointing directly to the publisher's server.

How to fix: Replace the redirected URL with the direct/final URL from the publisher's server.

Function Get-UrlResponse {
    Param
    (
        [Parameter(Mandatory = $true, Position = 0)]
        [string] $URL
    )
    try {
        $HTTP_Request = [System.Net.WebRequest]::Create($URL)
        $HTTP_Request.UserAgent = 'Microsoft-Delivery-Optimization/10.1'
        $HTTP_Response = $HTTP_Request.GetResponse()
        $ResponseUri = $HTTP_Response.ResponseUri
        $AbsoluteUrl = $HTTP_Response.ResponseUri.AbsoluteUri
        $HTTP_Status = [int]$HTTP_Response.StatusCode
        $ResponseLength = $HTTP_Response.ContentLength
        $Headers = @{}; $HTTP_Response.Headers.ForEach({ $Headers[$_] = $Http_Response.Headers[$_] })
    } catch {
        $HTTP_Status = 404
    }
    If ($null -eq $HTTP_Response) { $HTTP_Status = 404 }
    Else { $HTTP_Response.Close() }
    return @{
        Url           = $URL
        ResponseUrl   = $AbsoluteUrl
        ResponseCode  = $HTTP_Status
        ContentLength = $ResponseLength
        Headers       = $Headers
        Response      = $ResponseUri
    }
}

Installation Testing Errors

Validation-Unattended-Failed

What it means: The installer did not complete silently — it either timed out or required user interaction.

Common causes:

• Incorrect installer type (e.g., exe specified for a nullsoft, burn, or inno installer, or msi for wix) — WinGet handles silent switches automatically for known types, so a wrong type means the wrong switches are used
• Missing or incorrect silent install switches (/S, /silent, /quiet, etc.)
• The installer displays a dialog that blocks progress (license agreement, options screen)
• A dependency is missing on the test machine
• The exe installer type was specified instead of portable for an application that runs without an installer

How to fix:

1. Check that your InstallerType is correct — use nullsoft, inno, burn, or wix instead of generic exe or msi when applicable.
2. Verify your InstallerSwitches include the correct Silent and SilentWithProgress values.
3. Test locally:

   winget install --manifest <path-to-manifest>
   

4. Use Windows Sandbox to confirm the install completes without interaction.

Validation-Executable-Error

What it means: After installation, the test could not locate the primary application executable.

Common causes:

• The application installs to a non-standard location
• The application is a service or background process without a visible executable
• Installation did not complete successfully

How to fix: Ensure the application installs correctly and its main executable is discoverable. If the app is not a traditional desktop application, add a comment to the PR for engineer investigation.

Validation-Uninstall-Error

What it means: The application did not clean up completely during uninstall testing.

How to fix: Verify that your application uninstalls cleanly. Check the PR comments for specific details about what was left behind.

Validation-Installation-Error

What it means: A general error occurred during manual validation of the package.

How to fix: Check the accompanying PR comment for specific next steps.

Validation-Defender-Error

What it means: During dynamic testing (post-install), Microsoft Defender flagged a problem with the installed application.

How to fix:

1. Install the application and run a full Microsoft Defender scan.
2. If you can reproduce the detection, fix the binary or submit it for false positive analysis.
3. If you cannot reproduce it, add a comment to the PR for investigation.

Dependency Errors

Validation-MSIX-Dependency

What it means: The MSIX package has a dependency that could not be resolved during testing.

How to fix: Update the package to include the missing framework components or declare the dependency in the manifest's Dependencies section.

Validation-VCRuntime-Dependency

What it means: The package depends on a Visual C++ Runtime that was not available during testing.

How to fix: Either bundle the VC++ runtime with the installer or add the appropriate dependency to the manifest.

Other Validation Errors

Validation-Merge-Conflict

What it means: Your PR has a merge conflict with the base branch and cannot be validated.

How to fix: Resolve the merge conflict in your branch and push the updated commits.

Validation-Error

What it means: A general validation failure occurred during manual approval. This is a catch-all label.

How to fix: Read the accompanying PR comment for details on what failed and the next steps.

Error-Analysis-Timeout

What it means: The binary validation test timed out before completing.

How to fix: This is typically investigated by WinGet engineers. No action is usually required from you — the PR will be assigned for investigation.

Content Policy Labels

These labels indicate that something in your manifest metadata triggered a content policy review. Your PR will undergo additional manual review.

Internal Error Labels

These labels indicate a service-side issue. Your PR will be assigned to WinGet engineers automatically. No action is typically required from you.

Moderator-Applied Labels

These labels are applied by moderators during manual review and indicate issues that need author attention.

Quick Reference Table

Getting Help

• Re-run validation: A moderator can comment @wingetbot run on your PR to re-trigger the validation pipeline.
• Ask a moderator: Check recently closed PRs to find an active moderator and @mention them.
• File an issue: If you believe the failure is incorrect, open an issue.
• Matrix chat: Join the WinGet-pkgs Matrix room for quick questions.

For more information, see the official validation documentation.