Troubleshooting and Limits

Troubleshooting and limits

Read the JSON status, errors, warnings, coverage and truncation fields before interpreting an exit code. A tool can return useful findings while a required check remains incomplete.

Common failures

Symptom	Action
pxtk is not on PATH	Check pnpm's global executable path or run node <installed-package>/dist/pxtk.cjs.
A command in this wiki is unknown	Check --version and --help. The seven added workflows require 0.2.0 or newer.
Game selection or paths are invalid	Check Configuration, override order and explicit null versus omitted discovery.
invalid_arguments	Use installed help or MCP input discovery. Unknown fields reject the request. Create takes a positional kind, and read takes a positional file.
preview_required	Preview first, review it, then repeat the same request with its token. Launch uses start; writers use write.
stale_preview, stale_input or source_changed	Review a fresh preview or restart source paging after saved changes. Do not reuse a token against different inputs.
Outside-mod, linked or read-only destination	Choose an ordinary path inside the editable mod. Import/package have their documented distinct destination rules.
Incomplete Tiger validation	Check the executable, selected installation, config and compatibility reason. Keep reported findings visible.
Baseline refused	Ensure complete validation, unchanged comparison inputs and a new JSON destination in an existing mod folder.
Sharp cannot load its native runtime	Install with optional platform dependencies enabled and normal registry access. Do not assume a warm offline store can reproduce a fresh consumer installation.
MCP preview rejected by client permissions	Grant permission for that specific write-capable tool through the client. Read-tool success does not verify writer access.
Migration trust required	Review the artifact itself, then supply its exact SHA-256. Worker isolation is not a sandbox.

Validation evidence

complete means requested structural checks and Tiger finished without a known compatibility rejection. compatibility.status:"unknown" means support is not certified. An explicit Tiger warning about a newer unsupported game yields unsupported, incomplete validation and exit 2. Baseline creation and comparison are refused in that case, while findings remain visible.

Selected files limit structural checks, but Tiger still checks the whole mod. Structural checks cover supported saved text. Documentation source labels distinguish generated dumps, bundled snapshots and wiki data; they do not prove a patch match. A clean report does not establish in-game behavior.

Indexed coverage

Impact reports editable-mod callers and outgoing dependencies; read-only callers are outside its coverage. Its override catalog inherits the LSP's 2000-entry cap. Dynamic references can be missed by impact, localization coverage and rename. Unsupported rename kinds are refused rather than partially handled.

Conflict reports exclude vanilla and depend on verified profile loading policies. Unknown winners remain unknown. Binary inventory is not a hash of binary contents. Packaging metadata checks do not certify Steam acceptance. Migration plans do not apply themselves.

Read and edit identities cover their stated saved inputs. Indexed mod/dependency changes invalidate edit previews; vanilla is identified by installation and detected version, not by hashing the entire game. Concurrent manual vanilla edits require a fresh preview or validation target.

Resource limits

Boundary	Limit
Ordinary query/result limit	Default 20, accepted 1 to 200
Source pages	Default 100 lines/16,000 characters; maximum 200/64,000
Supported source file	16 MiB
Inspect excerpt	18 lines and 500 characters per line
CLI JSON argument file, edits/answers	4 MiB, UTF-8
Image batch	200 images, 16 megapixels per image, 64 MiB per file, 256 MiB compressed inputs
Game-log read	32 MiB
Migration file content preview	16,000 characters per before/after value
Migration worker diagnostics	8,000 characters combined stdout/stderr

Inspect all returned truncation flags. A shortened preview does not authorize unseen changes or unknown code.

Playtest checkpoints

$checkpointArgs = @("logs", "checkpoint", "--output", ".px-toolkit/before-playtest.json", "--json")
$preview = pxtk @checkpointArgs | ConvertFrom-Json
if ($LASTEXITCODE -ne 0) { throw "Checkpoint preview failed." }
$preview.data.files | Format-List file, content
# Review and create the checkpoint before the playtest.
pxtk @checkpointArgs --write --expect $preview.data.previewToken
# Reproduce the intended behavior in the game.
pxtk logs --since .px-toolkit/before-playtest.json --json

Runtime error.log can live outside generated script_docs; use --file for a specific saved log. Checkpoints store file identity, a complete-line byte offset and prefix hash. Rotation, truncation or rewritten prefixes reset the read and are reported. Incomplete final lines wait for a later read. Duplicate records retain occurrence counts and source locations; unparsed records stay visible. Checkpoints are new files and never overwrite old ones.

Launch platforms

Windows launch has process-fixture coverage. Linux fixtures use an isolated process namespace. On a normal Linux desktop, any unreadable same-user process can cause process_probe_failed, preserving duplicate-game protection. Real Linux game startup has not been tested; macOS startup is unsupported.

Registered .mod archives have path checks; metadata-format archives are unsupported. Engine user-directory redirection is unsupported. A launch result observes only the first second. running does not prove that the mod loaded, and exit code 0 can report an immediate exited state. Observe gameplay separately. Once started, the game stays open when the caller disconnects.