Skip to main content

How to Resolve Error "CS0625: Instance field marked with StructLayout(LayoutKind.Explicit) must have a FieldOffset" in C#

The Compiler Error CS0625 is a configuration error related to Struct Memory Layout. The message reads: "'Field' : instance field in types marked with StructLayout(LayoutKind.Explicit) must have a FieldOffset attribute".

In C#, the Common Language Runtime (CLR) usually handles how data is arranged in memory automatically (LayoutKind.Auto or Sequential). However, when you use [StructLayout(LayoutKind.Explicit)], you are telling the compiler: "I want to manually define the exact memory address (offset) for every single field in this struct."

Because you took manual control, the compiler refuses to guess where any field belongs. If you declare a field but fail to provide its address using the [FieldOffset] attribute, the compiler raises CS0625.

This guide explains how to calculate offsets and fix this error.

Understanding LayoutKind.Explicit​

LayoutKind.Explicit is primarily used for two reasons:

  1. Interop: Communicating with C/C++ structs or Windows API calls where specific binary padding is required.
  2. Unions: Creating a C-style union where multiple fields share the same memory space (e.g., treating an integer as 4 individual bytes).

When this mode is active, the compiler stops calculating memory padding. You must explicitly map every field to a byte offset relative to the start of the struct.

Scenario: Missing Offsets​

This error occurs when you apply the Explicit layout to a struct but define fields like a normal class.

Example of error:

using System.Runtime.InteropServices;

// We declare manual control with 'Explicit'
[StructLayout(LayoutKind.Explicit)]
public struct Packet
{
    // ⛔️ Error CS0625: instance field in types marked with 
    // StructLayout(LayoutKind.Explicit) must have a FieldOffset attribute.
    // The compiler asks: "At which byte does 'Header' start?"
    public int Header;

    public int Payload;
}

Solution: Apply FieldOffset Attribute​

To fix this, you must decorate every instance field with the [FieldOffset(byte_index)] attribute.

You need to know the size (in bytes) of your data types to calculate the positions correctly:

  • byte: 1 byte
  • int, float: 4 bytes
  • double, long: 8 bytes

Solution:

using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Explicit)]
public struct Packet
{
    // Start at byte 0
    [FieldOffset(0)]
    public int Header; 

    // An int is 4 bytes (0, 1, 2, 3).
    // So the next field must start at byte 4.
    [FieldOffset(4)]
    public int Payload;
}

public class Program
{
    static void Main()
    {
        var p = new Packet { Header = 1, Payload = 99 };
        // This now compiles successfully.
    }
}
warning

Overlapping: If you calculate wrong (e.g., putting Header at 0 and Payload at 2), the fields will overlap. Changing Header will partially corrupt Payload. In Explicit layout, this overlap is allowed (and sometimes intended), so be careful with your math.

Advanced Usage: Creating Unions​

The most common valid reason to use Explicit layout is to create a Union, where two fields purposely occupy the exact same memory address.

For example, representing a 32-bit color as both an int and separate byte components.

using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Explicit)]
public struct ColorUnion
{
    // View 1: The entire color as a single integer
    [FieldOffset(0)]
    public int ArgbValue;

    // View 2: The Blue component (Low byte)
    [FieldOffset(0)]
    public byte Blue;

    // View 3: The Green component
    [FieldOffset(1)]
    public byte Green;

    // View 4: The Red component
    [FieldOffset(2)]
    public byte Red;

    // View 5: The Alpha component (High byte)
    [FieldOffset(3)]
    public byte Alpha;
}

In this setup, writing to ArgbValue automatically updates Blue, Green, Red, and Alpha because they physically share the same bytes in RAM.

Conclusion​

CS0625 enforces the "Explicit" part of explicit layout.

  1. Import Namespace: Ensure you are using System.Runtime.InteropServices.
  2. Add Attributes: Every public or private field must have [FieldOffset(x)].
  3. Calculate Size: Ensure offsets account for the size of previous types (e.g., add 4 for ints, 8 for doubles) unless you intentionally want a Union.

Table of Contents