dotnet pack "NU5039: readme file does not exist" in CI

By Kaveh Alemi·Latchkey

A PackageReadmeFile is declared but the referenced README is not actually included in the package, so dotnet pack fails NU5039. The file path is wrong, or it is not added with Pack="true" to the package root.

What this error means

dotnet pack fails with NU5039 saying the readme file does not exist in the package (or NU5046 that the element is not specified). It is deterministic and tied to the project’s README packing configuration.

dotnet pack output

error NU5039: The readme file 'README.md' does not exist in the package.

Diagnose it: SDK version and restore first

Most .NET CI failures are an SDK mismatch or a restore that did not happen. global.json pins the SDK, and if the runner does not have that exact version the failure message is about the project rather than the SDK.

Terminal

dotnet --info
cat global.json 2>/dev/null

# restore explicitly so a restore failure is not reported as a build failure
dotnet restore --verbosity normal
dotnet build --no-restore -warnaserror

Common causes

README declared but not packed

The project sets <PackageReadmeFile>README.md</PackageReadmeFile> but never adds the file to the package via a <None Include="README.md" Pack="true" PackagePath="\" /> item, so it is missing from the .nupkg.

Wrong path or package path for the README

The README lives in a different directory than expected, or its PackagePath does not place it at the package root where NuGet looks.

How to fix it

Include the README in the package

Declare the readme file and pack it to the package root.

.csproj

<PropertyGroup>
  <PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup>
<ItemGroup>
  <None Include="README.md" Pack="true" PackagePath="\" />
</ItemGroup>

Confirm the path resolves at pack time

Verify the README path is relative to the project and exists in the checkout.
Pack and inspect the .nupkg (it is a zip) to confirm the README is at the root.
Fix PackagePath if the file landed in a subfolder instead of the root.

How to prevent it

Pack the README with Pack="true" PackagePath="\" whenever PackageReadmeFile is set.
Keep PackageReadmeFile and the packed filename identical.
Inspect the produced .nupkg contents as a CI step for packaged libraries.

Frequently asked questions

What causes dotnet pack "NU5039: readme file does not exist" in CI?

There are 2 common causes: readme declared but not packed and wrong path or package path for the readme. The project sets <PackageReadmeFile>README.md</PackageReadmeFile> but never adds the file to the package via a <None Include="README.md" Pack="true" PackagePath="\" /> item, so it is missing from the .nupkg.

How do I fix dotnet pack "NU5039: readme file does not exist" in CI?

There are 2 fixes depending on which cause you have: include the readme in the package and confirm the path resolves at pack time. Work through them in order, since the first is the most common.

What does dotnet pack "NU5039: readme file does not exist" in CI actually mean?

dotnet pack fails with NU5039 saying the readme file does not exist in the package (or NU5046 that the element is not specified).

How do I stop dotnet pack "NU5039: readme file does not exist" in CI happening again?

Pack the README with Pack="true" PackagePath="\" whenever PackageReadmeFile is set. The prevention section lists 3 changes that keep it from recurring.