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.
Tip
Many issues can be caught before submitting by running:
winget validate <path-to-manifest>
winget install --manifest <path-to-manifest>For isolated testing, use the SandboxTest.ps1 script or Windows Sandbox.
- Status Labels
- Error Labels
- Content Policy Labels
- Internal Error Labels
- Moderator-Applied Labels
- Quick Reference Table
These labels track the progress of your PR through the validation pipeline.
| Label | Meaning |
|---|---|
| Azure-Pipeline-Passed | Your manifest passed automated testing. There may be additional manual verification required. |
| Validation-Completed | All checks passed. Your PR may be merged automatically after moderator review. |
| Needs-Author-Feedback | Something needs your attention. If not addressed within 10 days, the PR will be auto-closed. |
| Needs-Attention | The PR has been escalated to the WinGet engineering team for investigation. |
| Blocking-Issue | The PR cannot be approved until the blocking issue (indicated by an accompanying error label) is resolved. |
| Needs-CLA | You have not signed the Contributor License Agreement. The PR cannot be merged until the CLA is signed. |
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.
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.
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 —
PackageIdentifierand 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.
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.
What it means: There are inconsistencies or missing values in the manifest discovered during MSIX package evaluation or installer metadata validation.
Common causes:
InstallerTypemismatch between what is declared and what is detected- Missing or incorrect
PackageFamilyNamefor MSIX packages - Incorrect
MinimumOSVersionfor MSIX packages - Inconsistencies in
AppsAndFeaturesEntries
How to fix: Verify that installer metadata matches the actual installer. For MSIX, ensure PackageFamilyName and SignatureSha256 are correct.
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:
- Verify the
InstallerSha256hash:winget hash <path-to-installer>
- If flagged as malware/PUA, submit the installer to Microsoft Defender for analysis as a potential false positive.
- Ensure the installer URL is publicly accessible.
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.
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.
What it means: The validation service could not download the installer.
Common causes:
- The
InstallerUrlis 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.
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:
- Check that all URLs in the manifest are valid and accessible.
- If the issue is reputation-based, submit the URL for review.
- Look at the PR check details to identify which specific URL failed.
What it means: The InstallerUrl does not use HTTPS.
How to fix: Update the InstallerUrl to use https:// instead of http://.
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.
Tip
Including PackageUrl in your manifest and ensuring the InstallerUrl can be found by navigating the publisher's website from that URL helps speed up moderator reviews.
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.
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.
PowerShell: Find the final URL after redirects
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
}
}What it means: The installer did not complete silently — it either timed out or required user interaction.
Common causes:
- Incorrect installer type (e.g.,
exespecified for anullsoft,burn, orinnoinstaller, ormsiforwix) — 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
exeinstaller type was specified instead ofportablefor an application that runs without an installer
How to fix:
- Check that your
InstallerTypeis correct — usenullsoft,inno,burn, orwixinstead of genericexeormsiwhen applicable. - Verify your
InstallerSwitchesinclude the correctSilentandSilentWithProgressvalues. - Test locally:
winget install --manifest <path-to-manifest>
- Use Windows Sandbox to confirm the install completes without interaction.
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.
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.
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.
What it means: During dynamic testing (post-install), Microsoft Defender flagged a problem with the installed application.
How to fix:
- Install the application and run a full Microsoft Defender scan.
- If you can reproduce the detection, fix the binary or submit it for false positive analysis.
- If you cannot reproduce it, add a comment to the PR for investigation.
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.
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.
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.
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.
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.
These labels indicate that something in your manifest metadata triggered a content policy review. Your PR will undergo additional manual review.
| Label | Policy |
|---|---|
| Policy-Test-2.1 | General Content Requirements |
| Policy-Test-2.2 | Content Including Names, Logos, Original and Third Party |
| Policy-Test-2.3 | Risk of Harm |
| Policy-Test-2.4 | Defamatory, Libelous, Slanderous and Threatening |
| Policy-Test-2.5 | Offensive Content |
| Policy-Test-2.6 | Alcohol, Tobacco, Weapons and Drugs |
| Policy-Test-2.7 | Adult Content |
| Policy-Test-2.8 | Illegal Activity |
| Policy-Test-2.9 | Excessive Profanity and Inappropriate Content |
| Policy-Test-2.10 | Country/Region Specific Requirements |
| Policy-Test-2.11 | Age Ratings |
| Policy-Test-2.12 | User Generated Content |
These labels indicate a service-side issue. Your PR will be assigned to WinGet engineers automatically. No action is typically required from you.
| Label | Description |
|---|---|
| Internal-Error | Generic or unknown failure during testing. |
| Internal-Error-Domain | Error during URL domain validation. |
| Internal-Error-Dynamic-Scan | Error during post-install binary validation. |
| Internal-Error-Keyword-Policy | Error during manifest content policy validation. |
| Internal-Error-Manifest | Error during manifest processing. |
| Internal-Error-NoArchitectures | Could not determine the installer architecture. |
| Internal-Error-NoSupportedArchitectures | The current test architecture is not supported. |
| Internal-Error-PR | Error during PR processing. |
| Internal-Error-Static-Scan | Error during static analysis of installers. |
| Internal-Error-URL | Error during URL reputation validation. |
These labels are applied by moderators during manual review and indicate issues that need author attention.
| Label | Meaning |
|---|---|
| Error-Hash-Mismatch | Installer hash doesn't match — same as the automated label. |
| Error-Installer-Availability | Installer URL cannot be reached. |
| Interactive-Only-Installer | The installer requires user interaction and cannot run silently. This is a blocking issue. |
| License-Blocks-Install | A license agreement blocks silent installation. This is a blocking issue. |
| Manifest-Content-Incomplete | Manifest metadata is missing or insufficient. |
| Manifest-Singleton-Deprecated | Singleton manifests are no longer accepted — convert to multi-file format. |
| Version-Parameter-Mismatch | The version in the manifest doesn't match what the installer writes to the registry. |
| Portable-Archive | The installer is a portable archive that may need special handling. This is a blocking issue. |
| Scripted-Application | The package uses scripts (.bat, .ps1) as installers, which are not allowed. |
| Hardware | The package requires specific hardware. This is a blocking issue. |
| Label | Category | Author Action Required? | Summary |
|---|---|---|---|
Manifest-Validation-Error |
Manifest | ✅ Yes | Fix YAML syntax / schema errors |
Manifest-Version-Deprecated |
Manifest | ✅ Yes | Update to a supported schema version |
Manifest-Path-Error |
Manifest | ✅ Yes | Fix directory structure / file naming |
PullRequest-Error |
PR | ✅ Yes | One package, one version per PR |
Manifest-Installer-Validation-Error |
Manifest | ✅ Yes | Fix installer metadata inconsistencies |
Binary-Validation-Error |
Installer | ✅ Yes | Fix AV detection or hash/URL issues |
Error-Hash-Mismatch |
Installer | ✅ Yes | Update InstallerSha256 |
Error-Installer-Availability |
Installer | ✅ Yes | Fix installer URL |
URL-Validation-Error |
URL | ✅ Yes | Fix broken or untrusted URLs |
Validation-HTTP-Error |
URL | ✅ Yes | Switch to HTTPS |
Validation-Domain |
URL | Use publisher's official URL | |
Validation-Unapproved-URL |
URL | Use approved publisher URL | |
Validation-Indirect-URL |
URL | ✅ Yes | Remove URL redirection |
Validation-Unattended-Failed |
Install | ✅ Yes | Fix silent install switches |
Validation-Executable-Error |
Install | Verify executable is discoverable | |
Validation-Defender-Error |
Install | Fix or submit for false positive review | |
Validation-Merge-Conflict |
PR | ✅ Yes | Resolve merge conflict |
Validation-MSIX-Dependency |
Dependency | ✅ Yes | Add missing framework dependency |
Validation-VCRuntime-Dependency |
Dependency | ✅ Yes | Add VC++ runtime dependency |
Needs-CLA |
PR | ✅ Yes | Sign the Contributor License Agreement |
Internal-Error-* |
Internal | ❌ No | WinGet team will investigate |
Policy-Test-* |
Content | Additional manual review required |
- Re-run validation: A moderator can comment
@wingetbot runon your PR to re-trigger the validation pipeline. - Ask a moderator: Check recently closed PRs to find an active moderator and
@mentionthem. - 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.