rk decode-stack

The rk decode-stack command translates a raw Hermes or JavaScript stack trace to the TypeScript file, line, and column positions of the code that produced it.

You must run the command from your app root directory (the folder that contains roku-config.ts). The command automatically locates the most recent dist-dev/bundle or dist-build/bundle directory and picks the matching source maps.

The command accepts a stack trace that you paste, pipe from a file or a device stream, or pass as an argument. It can write colored text, plain text, or JSON output.

Usage

The following commands show how to run the command:

# Paste stack trace, then Ctrl+D
npx rk decode-stack

# With options or inline text
npx rk decode-stack [options] [stack-trace-text]

Options

See rk decode-stack for more information about every option, alias, and default.

The following behaviors apply to specific options:

• The --sha option falls back to auto-detection without reporting an error when the directory for the SHA does not exist. You should check the SHA before you trust the result.
• The --dcl-dir option requires the libName= prefix. You must repeat the option once for each library.
• The --stream option cannot be combined with --file.
• The --output option writes plain text unless you pass a format.

Quick examples

The following examples show common ways to run the command:

# Paste stack trace interactively, then press Ctrl+D to decode
npx rk decode-stack

# Decode a saved log file
npx rk decode-stack --file crash.log

# Pipe from clipboard (macOS)
pbpaste | npx rk decode-stack

# Pipe from a log file
cat production.log | npx rk decode-stack

# Inline stack trace as an argument
npx rk decode-stack "  at handleFocus (index.hbc:1:46343)"

# Live stream from a device
telnet <ROKU_IP> 8085 | npx rk decode-stack --stream

# Machine-readable JSON output
npx rk decode-stack --json < error.log

# Plain text output (no ANSI colors)
npx rk decode-stack --format plain --file error.log

# Show 5 lines of context around each crash site
npx rk decode-stack -c 5 --file error.log

# Point at an archived build by SHA
npx rk decode-stack --sha 4a7f3c8e --file crash.log

# Point at an archived build directory + SHA
npx rk decode-stack --build-dir /archive/builds --sha 4a7f3c8e -f crash.log

# Write decoded output to a file (plain format by default)
npx rk decode-stack --file crash.log --output decoded.txt

# Write JSON output to a file
npx rk decode-stack --file crash.log --output report.json --json

# Increase stdin timeout for very large log files
npx rk decode-stack --timeout 60000 < large-log.txt

Detecting the SHA automatically

In non-stream (batch) mode, the decode-stack command reads the full input before it resolves source maps. If you do not provide --sha, the command scans the input for source_map_sha=<hex> or [SourceMap: <hex>] patterns and uses the extracted SHA to locate the correct build artifacts. As a result, you can pipe a raw Roku log that contains the SHA tag, and the command finds the right source map without any extra flags. The following example shows this:

# The SHA is embedded in the stack trace; --sha is not needed
pbpaste | npx rk decode-stack

The --sha flag always takes precedence over auto-detection.

Note: In --stream mode, SHA auto-detection is not available because the command must resolve the bundle before it reads stdin. When you use --stream, you must pass --sha or --build-dir. The following example shows --stream with --sha:

Bash

telnet <ROKU_IP> 8085 | npx rk decode-stack --stream --sha 4a7f3c8e

Output formats

The --format option selects one of the formats in the following table:

Integrating with error tracking

You can feed decoded stack traces into error-tracking and monitoring pipelines with the --json output format. The following examples show two ways to use the output:

# Decode and POST to an ingestion endpoint
npx rk decode-stack --json -f crash.log | curl -X POST \
  -H 'Content-Type: application/json' \
  -d @- https://errors.example.com/api/ingest

# Extract only the source paths with jq
npx rk decode-stack --json < error.log | jq '.[].source'

For programmatic integration (for example, Sentry beforeSend or Bugsnag onError), you should use the @roku-sdk/stack-decoder TypeScript API instead of spawning the CLI. See Setting up monitoring integrations for more information.

Related documentation

• Mapping runtime errors to TypeScript source code: Explains source maps, bundle resolution, output formats, and troubleshooting.
• rk decode-stack: Lists every option, alias, and default for the rk decode-stack command.