07/troubleshooting

Troubleshooting & Failure Modes

The symptoms that show up after a protected deploy, what causes them, and the first command to run for each.

A hydrated page stops matching the server markup

unpeek only opens client output directories: `.next/static/chunks`, `dist/assets`, and `build/static/js`. Server bundles under `.next/server` are never parsed, so React server rendering stays untouched.

If a mismatch appears anyway, confirm the protected directory with `--out-dir` and check that it points at the client output rather than the project root. A wrong `--out-dir` is the only way protection reaches a server bundle.

Terminal: Point the CLI at the client output
# Explicit target, passive shield, deterministic seed
unpeek protect --out-dir .next/static/chunks --passive --seed 0x7f4a2c

Production stack traces show mangled symbols

Source maps are moved into `.unpeek-maps/` and the `//# sourceMappingURL=` comment is stripped from the public bundle, so the browser has nothing to resolve. Upload the vault to your error tracker instead of the public directory.

  • Point the Sentry or Datadog upload step at `.unpeek-maps/`, never at the public output.
  • Keep `.unpeek-maps/` in `.gitignore`. `unpeek init` appends the entry for you.
  • Use `--no-maps` when the vault is not needed and the maps should be deleted outright.

A slow function was not marked hot

`TRUE_HOT_60FPS` propagates from loops, `requestAnimationFrame`, and `useFrame`. Shallow UI render components only keep their direct render frame hot so nested handlers (`onSubmit`, `handleSave`) still receive cold hardening.

If a profile shows vault cost inside a hot helper outside the loop graph, invoke it from a detected frame loop or raise `--min-string-length` so fewer literals enter the vault.