---
title: "LZ4 frame variants and interoperability"
url: https://recursiveai.org/onearchive/articles/lz4-frame-variants-and-interop/
description: "Standard LZ4 frames start with 04 22 4D 18. OneCompress’s Lz4.Decompress reads standard, legacy, skippable, and concatenated frames in one call."
date: 2026-11-19
author: OneArchive team
---

# LZ4 frame variants and interoperability

Standard LZ4 frames start with 04 22 4D 18. OneCompress’s Lz4.Decompress reads standard, legacy, skippable, and concatenated frames in one call.

November 19, 2026 · OneArchive team · Updated · November 19, 2026

**OneArchive** is a free, open-source ([MIT or Apache-2.0](https://licenses.nuget.org/MIT%20OR%20Apache-2.0)) archive and compression library for .NET from Recursive AI. Its OneCompress package reads LZ4 frames. [NuGet](https://www.nuget.org/packages/RecursiveAI.OneCompress/1.2.0) · [GitHub](https://github.com/recursive-ai-oss/onearchive-csharp) · [Docs](https://recursiveai.org/onearchive/docs/).

## Quick start

For a plain file round trip, see [compress and decompress LZ4 in C#](https://recursiveai.org/onearchive/cookbook/lz4-compress-decompress/).

From an empty directory with the .NET 10 SDK:

```
dotnet new console -f net10.0
dotnet add package \
  RecursiveAI.OneCompress \
  --version 1.2.0
```

This input puts an empty skippable member between two standard frames for `hi`. The skippable member adds no output.

Replace `Program.cs` with the following and run `dotnet run`.

*Program.cs · .NET 10*

```
using System.Text;
using RecursiveAI.OneCompress.Lz4;
 
byte[] frame = Lz4.Compress("hi"u8.ToArray());
// Skippable magic, then a 4-byte length of 0.
byte[] skip = [0x50, 0x2A, 0x4D, 0x18, 0, 0, 0, 0];
byte[] input = [..frame, ..skip, ..frame];
Console.WriteLine(Encoding.UTF8.GetString(Lz4.Decompress(input)));
```

*Output · Text*

```
hihi
```

## Identify the bytes before choosing a decoder

Look at the first four bytes at a known frame boundary, not the filename extension. A standard LZ4 frame starts with a magic number and settings, then holds compressed or uncompressed data blocks and can include optional checksums. A raw LZ4 block has no frame header; the enclosing format must tell you where it ends and supply a bound on its decoded size. In OneCompress 1.2.0, `Lz4` handles frames and `Lz4Block` handles raw blocks. An unrecognized magic number does not by itself prove the input is a raw block.

### Standard frame

`04 22 4D 18`, followed by a descriptor and length-prefixed blocks. Check the descriptor for the checksum flags, dictionary ID, and whether blocks share history. A zero block-size field marks the end of blocks; a flagged content checksum still follows it.

### Legacy frame

`02 21 4C 18`, followed by length-prefixed compressed blocks. No standard descriptor, dictionaries, or checksums. Look for the next recognized frame magic or end of input at a block boundary.

### Skippable frame

`50 2A 4D 18` through `5F 2A 4D 18`, followed by a length and that many bytes. Produces no decoded payload. Set `SkippableFrameHandler` if you need its bytes. `MaxSkippableFrameSize` defaults to 1 MiB.

### Concatenated frames

Another frame starts at the boundary after the previous one; no separate magic for the sequence. Decode members in order. Block history does not carry from one member to the next. Bytes after the last valid member must form another frame, not arbitrary padding.

The byte order above is the order on disk. See the [LZ4 frame specification](https://github.com/lz4/lz4/blob/v1.10.0/doc/lz4_Frame_format.md) for the format and the [OneCompress decoder reference](https://github.com/recursive-ai-oss/onearchive-csharp/blob/51053d161cb81164dd4380710afd9ebd8d0243c7/docs/lz4-decoder.md#L41-L81) for reader behavior.

## Why the same payload may need different reader settings

- **Checksum failure:** the standard header checksum covers the descriptor. Optional block checksums cover the stored block bytes, before decoding; the optional content checksum covers the decoded content. OneCompress checks block and content checksums by default. `VerifyChecksum = false` does not disable the header check.
- **Missing dictionary:** the frame can carry an ID, not the dictionary bytes. OneCompress looks up a nonzero ID in `Dictionaries`, then falls back to `Dictionary` if its ID matches or is zero. For a known dictionary-compressed stream without a nonzero ID, supply `Dictionary` explicitly. Only the last 64 KiB of dictionary bytes are used.
- **Only the first member is decoded:** a streaming `Lz4Decoder` returning `Done` at a frame boundary does not mean the input is exhausted. Keep track of bytes consumed and pass the remaining bytes to the decoder. A skippable member can reach a boundary with zero output. A legacy frame may end at input EOF without producing a separate `Done`; see the [streaming contract](https://github.com/recursive-ai-oss/onearchive-csharp/blob/51053d161cb81164dd4380710afd9ebd8d0243c7/docs/lz4-decoder.md#L89-L95).

## A mixed-frame input decoded in one call

Replace the quick-start program with this example. It builds the entire input in memory: a standard frame for `one`, a skippable member carrying `!`, a legacy member with a literal-only block for `two`, and the original standard frame again. The legacy block’s `0x30` token means three literal bytes and no match. The second standard magic marks the end of the legacy member.

*Program.cs · .NET 10*

```
using System.Text;
using RecursiveAI.OneCompress.Lz4;
 
byte[] standard = Lz4.Compress("one"u8.ToArray());
byte[] skip = [0x53, 0x2A, 0x4D, 0x18, 1, 0, 0, 0, (byte)'!'];
byte[] legacy = [0x02, 0x21, 0x4C, 0x18, 4, 0, 0, 0,
                 0x30, (byte)'t', (byte)'w', (byte)'o'];
byte[] input = [..standard, ..skip, ..legacy, ..standard];
Console.WriteLine($"Standard: {Convert.ToHexString(standard.AsSpan(0, 4))}");
Console.WriteLine($"Skippable: {Convert.ToHexString(skip.AsSpan(0, 4))}");
Console.WriteLine($"Legacy: {Convert.ToHexString(legacy.AsSpan(0, 4))}");
Console.WriteLine($"Decoded: {Encoding.UTF8.GetString(Lz4.Decompress(input))}");
```

*Output · Text*

```
Standard: 04224D18
Skippable: 532A4D18
Legacy: 02214C18
Decoded: onetwoone
```

The output contains both copies of `one` and the legacy `two`, but not the skippable byte.
