Explain 0x80073CF9 instead of surfacing a bare HRESULT

[Alexandre Zollinger Chohfi (azchohfi)]

What

Maps ERROR_INSTALL_REGISTRATION_FAILURE (0x80073CF9) to an actionable hint in
BuildRegistrationException, following the existing ERROR_INSTALL_PACKAGE_ALREADY_EXISTS
precedent:

Hint: this usually means a file inside the package layout exceeds the Windows MAX_PATH limit
of 260 characters. The manifest path itself is validated before registration, but a nested
payload file in a deep build-output folder can still exceed it. Re-run with the layout staged
somewhere short:
  winapp run --output-appx-directory C:\Tmp\<AppName>

Why

0x80073CF9 arrives with no error text, so the caller sees only
Failed to register package: Unknown error (0x80073CF9).

The gap is specific: PackageRegistrationService already calls
LongPathHelper.ValidatePathLength(fullPath), but that validates the manifest path only. A
manifest can sit well under 260 characters while a nested payload file in
bin/x64/Debug/net10.0-windows10.0.26100.0/win-x64/... does not. Registration then fails inside the
WinRT PackageManager with an HRESULT nothing maps.

Measured cost, from an agent's own retrospective on a run that ultimately succeeded:

time_sinks:    Package registration diagnosis: 4 attempts to identify MAX_PATH as root cause
missing_tools: A diagnostic for MAX_PATH issues with package registration would have saved 3 cycles

On other runs the same condition was fatal and surfaced as three unrelated-looking errors —
Unknown error (0x80073CF9), Failed to reach state Staged, and Manifest file not found against
the staged copy — none of which name the cause.

Tests

Two, matching the file's existing style: one asserting the hint appears for 0x80073CF9, one
asserting it does not leak onto unrelated HRESULTs.

Note: dotnet test discovers 0 tests in this project on my machine — but it also discovers 0 on a
pristine checkout, so that appears to be a local environment issue rather than anything this change
introduces. The test code compiles cleanly.

[Copilot]

Pull request overview

Adds actionable diagnostics for package registration failure 0x80073CF9.

Changes:

• Adds MAX_PATH remediation guidance.
• Adds focused exception-message tests.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
PackageRegistrationService.cs	Maps the HRESULT to troubleshooting guidance.
PackageRegistrationServiceTests.cs	Verifies hint inclusion and isolation.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.