Skip to main content

How to Resolve Error "CS0690: Input file 'file' contains invalid metadata" in C#

The Compiler Error CS0690 is a file integrity error. The message reads: "Input file 'MyLibrary.dll' contains invalid metadata."

In the .NET ecosystem, every compiled assembly (.dll or .exe) contains Metadata—a structured binary section that describes the types, methods, and properties defined within that file. When the C# compiler references another library, it reads this metadata to validate your code. CS0690 means the compiler successfully found and opened the file, but the metadata section was corrupted, incomplete, or formatted in a way the compiler could not parse.

This is rarely a code syntax error; it is almost always an environment, build process, or file version issue.

Understanding Metadata Corruption​

A valid .NET assembly follows the ECMA-335 standard. The compiler expects specific headers and data tables.

Common causes for metadata failure:

  1. Partial Write: A previous build crashed or was interrupted while writing the .dll, leaving a truncated file.
  2. Disk Error: Physical corruption on the hard drive.
  3. Bad Download: A NuGet package was downloaded incorrectly (0-byte file or HTML error page saved as .dll).
  4. Locking: Antivirus or another process locked the file during a write operation.

Scenario 1: Corrupted Build Artifacts (The "Clean" Fix)​

This is the cause in 90% of cases. The obj or bin folders contain a "stale" or broken version of a dependency.

Symptoms​

You haven't changed the referenced library, but suddenly the main project refuses to build, claiming the library is invalid.

Solution: Force a Clean Rebuild​

Do not just click "Build". You need to wipe the old files.

  1. Close Visual Studio (to release file locks).
  2. Navigate to your solution folder in File Explorer.
  3. Delete the bin and obj folders manually in both the referenced project and the consuming project.
  4. Reopen and Rebuild.

Alternatively, use the command line:

# ✅ Correct: Wipes previous build artifacts completely
dotnet clean
dotnet build --no-incremental

Scenario 2: Referencing Non-Managed DLLs​

The C# compiler (csc.exe) can only reference Managed .NET assemblies. If you attempt to add a reference to a Native C++ DLL or a standard Windows DLL (like user32.dll), the compiler will try to read .NET metadata, fail to find the CLR header, and throw CS0690 (or sometimes CS0009).

Example of error​

Adding a native DLL to the "References" or "Dependencies" list.

<!-- .csproj file -->
<ItemGroup>
  <!-- ⛔️ Error CS0690: This is a C++ DLL, it has no .NET metadata. -->
  <Reference Include="MyNativeLib.dll" />
</ItemGroup>

Solution: Use P/Invoke​

If the library is native, you cannot reference it. You must copy it to the output folder and use [DllImport].

using System.Runtime.InteropServices;

public class Wrapper
{
    // ✅ Correct: Load the native DLL at runtime, don't reference at compile time.
    [DllImport("MyNativeLib.dll")]
    public static extern void NativeMethod();
}

Scenario 3: Compiler Version Mismatch​

In rare cases, you might be trying to reference a .dll built with a very recent version of .NET (e.g., .NET 8) using an ancient compiler (e.g., the compiler bundled with .NET Framework 4.5).

If the newer format uses metadata optimizations or version markers that the old compiler does not understand, it may report the metadata as "invalid."

Solution: Update Tooling​

Ensure your build environment matches the technology you are using.

  • Visual Studio: Update to the latest version (e.g., VS 2022 for .NET 6+).
  • NuGet: Ensure you aren't pulling a package that requires a newer .NET Standard than your project supports.
note

IL Weaving Tools: If you use tools like Fody, PostSharp, or Obfuscators, they modify the IL/Metadata after compilation. If these tools are buggy or misconfigured, they can produce invalid metadata. Try disabling these tools to see if the error persists.

Conclusion​

CS0690 is a signal that the file you are pointing to is broken.

  1. Clean Up: Delete bin and obj folders. This fixes most issues.
  2. Check File Type: Ensure you aren't referencing a Native C++ DLL or a corrupted 0-byte file.
  3. Check Tools: Disable IL weavers or Obfuscators temporarily.

Table of Contents