System.IO.FileNotFoundException "Could not load assembly" at runtime in CI

By Kaveh Alemi·Latchkey

A runtime FileNotFoundException for an assembly means the app compiled against a reference that is not present (or is the wrong version) at execution time. The CLR probed for the assembly, did not find a matching one, and threw. It is a deployment/binding gap, not a compile error.

What this error means

The app or test throws System.IO.FileNotFoundException: Could not load file or assembly naming the assembly and version. It reproduces deterministically for the published output.

System.IO.FileNotFoundException: Could not load file or assembly
'Newtonsoft.Json, Version=13.0.0.0, Culture=neutral, PublicKeyToken=30ad4fe6b2a6aeed'.
The system cannot find the file specified.

Common causes

An assembly was not copied to output

A reference marked CopyLocal=false, a trimmed publish, or a plugin-loaded assembly is absent from the runtime directory.

A binding version mismatch

The runtime found a different version than the one the app was compiled against, and no binding redirect resolves it.

How to fix it

Ensure the assembly ships and versions align

1. Confirm the dependency is published to the runtime output (check trimming/CopyLocal).
2. Align package versions so compile-time and runtime versions match.
3. Re-run after a clean publish.

dotnet publish -c Release -o out
ls out | grep -i newtonsoft

How to prevent it

• Pin dependency versions to avoid runtime binding drift.
• Be cautious with trimming; preserve assemblies loaded via reflection.

Frequently asked questions

Related guides

References

• .NET documentation
• GitHub Actions documentation