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 see | Most likely cause | Check |
|---|---|---|
Not all bytes read | The bytes hold more than your struct: a newer version with extra fields, a different instruction, or two values where you expected one | Compare the data length with what your struct consumes; look for a newer IDL |
Unexpected length of input | The bytes end before your struct does: an older version with fewer fields, or a wrong length prefix read earlier | Find the field where decoding stopped; check the program's history for added arguments |
Invalid Option representation: N. The first byte must be 0 or 1 | You are not at the start of an Option, usually because an earlier field was read with the wrong size | Recount the sizes of every field before it |
Invalid bool representation: N | Same as above: an offset error that happens to land on a bool | Same as above |
| A huge vector length, or an allocation failure | A u32 length prefix read from the wrong place | Print the 4 bytes you read as the length and where they sit |
| Decodes cleanly, values are nonsense | The 8-byte discriminator was not skipped, or the wrong instruction struct was used | Match 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#
- borsh-rs deserializer source (error messages) (checked 2026-11-18)
- Borsh specification (checked 2026-11-18)
- Anchor repository (instruction discriminators, Borsh as the default serialization) (checked 2026-11-18)
- Pump.fun public IDL (an example of arguments added over time) (checked 2026-11-18)
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.