pkg-debug

name	pkg-debug
description	Debug and troubleshoot @yao-pkg/pkg packaging issues — build failures, runtime crashes, missing assets, bloated binaries, native addon errors, cross-compile regressions, SEA sentinel problems, and patches/dictionaries.
when_to_use	"debug pkg", "pkg not working", "packaged binary crashes", "missing file in binary", "binary too large", "cross-compile broken", "native addon fails", "SEA error", "Multiple occurences of sentinel", "ERR_REQUIRE_ESM", "Cannot find module" in pkg context, "Cannot execute binary from snapshot"
user-invocable	true
disable-model-invocation	false
argument-hint	["description of the issue"]
allowed-tools	Read Bash Grep Glob Agent
effort	high

pkg Debugging & Troubleshooting

Diagnose and fix issues when packaging Node.js apps with @yao-pkg/pkg.

User's issue: $ARGUMENTS

Official docs: https://yao-pkg.github.io/pkg/

For the full pkg configuration schema, patches examples, dictionary format, and contributing guide, see reference.md.

Triage — Start here

Identify the failure stage:

Stage	Symptom	Jump to
Build	pkg exits with error before producing a binary	Build failures
Runtime	Binary produced but crashes/errors on launch	Runtime errors
Missing files	App runs but can't find assets/modules at runtime	Missing assets
Binary size	Binary is unexpectedly large	Binary bloat
Cross-compile	Build OK on host but binary broken on target	Cross-compile
Native addons	.node files fail to load	Native addons
SEA-specific	Enhanced SEA sentinel/blob/fuse errors	SEA issues

Diagnostic tools

CLI flags

pkg --debug app.js -o dist/app      # Inject diagnostic prelude (build-time)
pkg . --sea                          # Enhanced SEA (stock Node.js, no bytecode)
pkg . --no-bytecode                  # Standard mode without V8 bytecode
pkg . --options max-old-space-size=4096  # Bake Node.js flags into binary

Runtime environment variables

These work inside the packaged binary, not at build time.