Decoding · November 18, 2026 · 6 min read

Borsh pitfalls that break Solana decoders

Borsh errors in a Solana decoder are rarely bugs in Borsh. They are layout mismatches, and each error message points at a specific one.

A Borsh deserialization error almost always means your layout does not match the bytes. "Not all bytes read" means the data is longer than the struct you chose, "Unexpected length of input" means it is shorter, and an invalid Option or bool message means you are reading at the wrong offset, often because the discriminator was not skipped.

Symptom and cause#

The messages below come from the Rust borsh crate's deserializer. Other languages' Borsh libraries word them differently, but the causes are the same.

What you seeMost likely causeCheck
Not all bytes readThe bytes hold more than your struct: a newer version with extra fields, a different instruction, or two values where you expected oneCompare the data length with what your struct consumes; look for a newer IDL
Unexpected length of inputThe bytes end before your struct does: an older version with fewer fields, or a wrong length prefix read earlierFind the field where decoding stopped; check the program's history for added arguments
Invalid Option representation: N. The first byte must be 0 or 1You are not at the start of an Option, usually because an earlier field was read with the wrong sizeRecount the sizes of every field before it
Invalid bool representation: NSame as above: an offset error that happens to land on a boolSame as above
A huge vector length, or an allocation failureA u32 length prefix read from the wrong placePrint the 4 bytes you read as the length and where they sit
Decodes cleanly, values are nonsenseThe 8-byte discriminator was not skipped, or the wrong instruction struct was usedMatch the first 8 bytes against the IDL before decoding

Lengths: the u32 prefix on vectors and strings#

Borsh writes integers little-endian and prefixes every vector and string with its length as a u32. Fixed-size arrays have no prefix. A public key is 32 raw bytes with no prefix, because it is a fixed array.

Most offset errors trace back to one of two mistakes: treating a fixed array as a vector (reading 4 bytes too many), or treating a vector as a fixed array (reading 4 bytes too few). Write down the size of every field from the IDL before you write the decoder, and check the total against a real instruction's data length.

Enums and options: the tag byte#

An Option is one byte, 0 for none or 1 for some, followed by the value only when it is some. An enum is a one-byte variant index followed by that variant's fields. That means an Option or enum makes everything after it variable in position: you cannot jump to a later field by a fixed offset. Decode in order, every time.

Enum variant order matters too. The index is the variant's position in the definition, so if a program adds a variant in the middle of an enum, every later index shifts. That is a breaking change for decoders even though the program's own clients recompile without noticing.

Discriminators come before the payload#

Anchor instruction data starts with an 8-byte discriminator, and the Borsh-encoded arguments follow it. If you hand the whole buffer to a Borsh decoder, it reads the discriminator as your first fields, and either fails or, worse, succeeds with nonsense.

Match the discriminator first, pick the struct that belongs to it, then decode from byte 8 onward. Since Anchor 0.31, programs can set custom discriminators, so read them from the IDL rather than computing them yourself. Anchor discriminators shows both cases.

Trailing bytes and arguments that are not there#

Programs add arguments to existing instructions over time, and old clients keep sending the short form. Pump.fun's buy instruction is one public example: newer arguments were added, and transactions from older clients still omit them.

A strict Borsh decoder fails on the short form with "Unexpected length of input". The right handling is to accept data that ends exactly at an argument boundary and record the missing arguments as absent. Do not fill in defaults: "absent" and "zero" mean different things to anyone reading your data later. The reverse case, extra bytes after the last argument you know, usually means a newer layout; log it and keep the raw bytes rather than discarding them. IDL drift covers how to version these layouts.

Instructions that are not Borsh at all#

Not every program uses Borsh. The System program's instructions start with a 4-byte variant tag, and the SPL Token program's with a single byte. Raydium's AMM v4 uses its own layout with a one-byte tag. Running a Borsh decoder over those produces exactly the offset errors in the table above. Decide the encoding per program, from the program's source or IDL, before you decode a single byte.

When a clean decode is still wrong#

A decode that succeeds is not proof that it is right. Two layouts can consume the same number of bytes and produce plausible values from both. Instruction data also describes what the sender requested, not what happened: a decoded swap amount is the requested input, and the transaction may still have failed. Check a sample of decoded rows against confirmed data before you trust a new decoder.

Further reading#

Borsh encoding is the layout reference this post assumes. Reading an IDL shows where the field sizes come from, and decoding Anchor instructions puts the discriminator check and the Borsh decode together in code. To test your decoder on live instruction data, start from the quickstart.

Sources#

Raw shreds on your own server

Ultra Low Latency Shreds is $200 and Standard Shreds is $100. You pay in crypto, tell us which IPv4 address and UDP port should receive the stream, and we wire it up by hand.

Read nextIDL drift: when a program upgrade breaks your decoder