Kaitai Struct Compiler

0.11.0 verified Fri May 01 auth: no javascript

Kaitai Struct Compiler is a tool that generates parsers for binary data formats from a declarative YAML or JSON definition (KSY format). Current stable version is 0.11.0, released September 2025. It supports multiple target languages including C++, C#, Java, JavaScript, Python, Ruby, Rust, and Go. The compiler is part of the Kaitai Struct ecosystem, which provides a language-agnostic way to describe binary formats and then compile those descriptions into efficient, reusable parsers in various programming languages. Unlike hand-written parsers, Kaitai Struct ensures consistency across languages and reduces maintenance overhead. The compiler is distributed as a standalone JAR file, available via releases on GitHub.

Common errors

error Error: Cannot find module 'kaitai-struct/KaitaiStream' ↓

cause The runtime package 'kaitai-struct' is not installed or version mismatch.

fix

Run 'npm install kaitai-struct' to install the runtime.

error Error: Could not find or load main class io.kaitai.struct.Main ↓

cause Java is not installed or the JAR file is missing.

fix

Install JRE 8+ and ensure the kaitai-struct-compiler JAR is in the expected location.

error kaitai-struct-compiler: command not found ↓

cause The global npm installation path is not in PATH.

fix

Add npm global bin directory to PATH or reinstall with -g.

Warnings

breaking v0.9 changed the default target language from Java to JavaScript. ↓

fix Explicitly specify -t java if you previously relied on the default.

deprecated The --help flag outputs usage information; long-form options like --target are deprecated since v0.10. ↓

fix Use short flags (-t, -o) instead of long options.

gotcha Compiler requires Java Runtime Environment (JRE) 8 or later to run. ↓

fix Install JRE 8+ and ensure java is in PATH.

gotcha The npm package 'kaitai-struct-compiler' is a wrapper that downloads the JAR; it does not work offline. ↓

fix Download the JAR directly from GitHub releases if offline.

breaking In v0.10, the runtime package 'kaitai-struct' changed its import path for KaitaiStream. ↓

fix Use require('kaitai-struct/KaitaiStream') instead of require('kaitai-struct').

breaking v0.11 removed support for the --ksc-exception flag (no longer needed). ↓

fix Remove the flag from your compilation commands.

Install

npm install kaitai-struct-compiler

yarn add kaitai-struct-compiler

pnpm add kaitai-struct-compiler

Imports

KaitaiStructCompiler
wrong
```
npm install kaitai-struct-compiler --global
```
correct
```
npm install kaitai-struct-compiler
```
The compiler is a command-line tool, not a library. It is installed globally via npm for convenience.

compile

wrong

kaitai-struct-compiler --target=javascript myformat.ksy

correct

kaitai-struct-compiler -t javascript myformat.ksy

Use -t for target language, not --target. The short flag is -t.

BinaryParser
wrong
```
import { KaitaiStream } from 'kaitai-struct';
```
correct
```
import KaitaiStream from 'kaitai-struct/KaitaiStream';
```
KaitaiStream is a subclass exported from the npm package 'kaitai-struct' (the runtime library). The compiler generates code that uses this stream class.

Quickstart

Demonstrates installing the compiler, compiling a KSY file to JavaScript, and using the generated parser with the kaitai-struct runtime.

// First, install the compiler globally
npm install kaitai-struct-compiler -g

// Create a simple KSY file example.ksy
// (YAML format describing a binary format)
kaitai-struct-compiler -t javascript example.ksy

// The compiler outputs example.js, which can be used with the runtime:
npm install kaitai-struct

// In Node.js:
const KaitaiStream = require('kaitai-struct/KaitaiStream');
const Example = require('./example.js');

const buf = Buffer.from(...); // your binary data
const stream = new KaitaiStream(buf);
const parsed = new Example(stream);
console.log(parsed);