docs(snapshot): add V8 snapshot troubleshooting guide#6010
Conversation
Add a dedicated troubleshooting page (EN + zh-CN) covering how to diagnose which module makes a V8 startup snapshot fail to build or restore, and how to fix it: - the serializability rule (native bindings / libuv handles / lazy web-global getters) and when a dependency trips it at module-evaluation time - build-time vs restore-time failure signatures, with the exact error strings emitted by egg-bin / the generated worker entry / egg-scripts - diagnosis: NODE_DEBUG namespaces, a clean NODE_OPTIONS, --dry-run, --skip-bundle bisecting, --force-external confirmation - fixes: --force-external, egg.snapshot.lazyModules, the snapshot lifecycle hooks, deferring work out of module scope, avoiding the web globals - detailed failure modes (tegg @advice filePath, the lazy-external member proxy, runtime-asset ENOENT) and a configuration reference Also document the previously-undocumented egg.snapshot.lazyModules config in advanced/snapshot.md, cross-link the new page from it, and wire the page into the English and Chinese advanced sidebars. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
📝 WalkthroughWalkthroughAdds new "Snapshot Troubleshooting" documentation pages in English and Chinese, covering build/restore failure detection, diagnosis workflows, fix strategies, failure-mode details, and a configuration reference. Updates existing ChangesSnapshot Troubleshooting Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive troubleshooting guide for V8 Startup Snapshots in both English and Chinese, detailing build-time and restore-time failure modes, diagnostic steps, and common fixes. It also updates the VitePress sidebar configuration to include these new pages and enhances the main snapshot documentation with references to the troubleshooting guide, additional details on configuring lazy modules, and an expanded list of web globals replaced by stubs. I have no feedback to provide as there are no review comments.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## next #6010 +/- ##
==========================================
- Coverage 81.95% 81.94% -0.01%
==========================================
Files 677 677
Lines 20651 20651
Branches 4099 4099
==========================================
- Hits 16924 16922 -2
- Misses 3214 3215 +1
- Partials 513 514 +1 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Motivation
Building a V8 startup snapshot serializes the whole heap, so any dependency that
opens a socket, starts a timer, or initializes a native binding at
module-evaluation time can make the blob fail to build — or build and then crash
on restore. There was no guide for finding which module is responsible or how to
fix it.
What
New dedicated page
advanced/snapshot-troubleshooting.md(EN + zh-CN):bindings / libuv handles / lazy web-global getters) and when a dependency
trips it.
strings each emits (
killed by signal SIGSEGV,no blob was written,Check failed: current == end_slot_index,Aop Advice not found,Cannot find module, …).NODE_DEBUGnamespaces, a cleanNODE_OPTIONS,--dry-run,--skip-bundlebisecting,--force-externalconfirmation.
--force-external,egg.snapshot.lazyModules, the snapshotlifecycle hooks, deferring work out of module scope, avoiding the web globals.
@AdvicefilePath, the lazy-external memberproxy, runtime-asset
ENOENT) and a configuration reference table.Also documents the previously-undocumented
egg.snapshot.lazyModulesconfig inadvanced/snapshot.md, cross-links the new page from it, and wires the page intothe English and Chinese advanced sidebars.
Docs-only; no runtime code change. Builds on the snapshot feature already on
next(#5998 / #5999 / #6001 / #6003).Test evidence
vitepress build sitepasses clean — VitePress's dead-link/anchor check isgreen, so both new pages render and every cross-file and in-page anchor
resolves (the two detail headings use explicit ASCII
{#…}ids because theVitePress slugifier retains CJK + fullwidth
「」).egg-bundler/egg-bin/egg-scriptssource — exact error strings, flagnames, debug namespaces, and the default lazy-module set.
🤖 Generated with Claude Code
Summary by CodeRabbit