SAYLOR Resolve runtime mismatches, lockfile conflicts, native modules, install scripts, package corruption, and memory failures while preserving reproducibility.
The result you're building
A reproducible JavaScript runtime environment using the project-declared runtime/package manager and lockfile, passing install/build/test/start without global-package or cache guesswork.
Use this guide when
- Installs abort, native modules fail, lockfiles conflict, scripts core-dump, or Node/Bun versions disagree.
- A project works only with deleted lockfiles or global packages.
Do not use it as a substitute for
- Do not delete the committed lockfile as the first fix.
- Do not mix npm, pnpm, yarn, and Bun lockfiles in one repair without an intentional migration.
Before you change anything
- Collect the items below first. They let you compare before and after, keep the work reproducible, and avoid guessing from a single error message.
- Repository commit, package.json engines/packageManager, lockfiles, and scripts.
- Runtime/package-manager versions and architecture.
- Complete first install/build error, memory/disk state, and native toolchain need.
- Whether lifecycle scripts are trusted and allowed.
Understand the system before fixing it
The lockfile is the reproduction contract
Frozen installs reveal whether committed dependencies can be recreated. Regenerating first hides the defect.
Runtime compatibility includes native ABI
Native addons can require a matching Node ABI, compiler, libc, Python, or prebuilt binary.
Core dump can be resource or binary failure
Capture kernel/journal signal, memory, architecture, and exact executable before reinstalling.
Evidence-to-decision map
| Evidence | Likely layer | First decisive check | What the result means |
|---|---|---|---|
| Frozen install rejects lockfile | Manifest/lock mismatch | Use declared package manager and inspect diff | Repository committed inconsistent dependency state. |
| Unsupported engine/syntax | Runtime version | Compare engines/packageManager and CI | Use project version; do not patch dependencies yet. |
| node-gyp/native build fails | ABI/toolchain | Read first compiler/download error | Missing supported prebuild, headers, compiler, Python, or architecture. |
| Killed/core dumped | Resource/runtime | Exit signal, journal, RAM/swap/disk, architecture | OOM, illegal instruction, corrupt binary, or runtime bug. |
Step-by-step procedure
Work in order. Record the output after each step. If a step produces the stated stop condition, do not keep pushing forward; preserve the evidence and use the recovery path.
Step 01 — Fingerprint project contract
Why: Multiple lockfiles and global tools create ambiguity.
Do: Record commit, engines, packageManager, scripts, lockfile types, and CI runtime.
Read the result: CI/version files are strong evidence for intended runtime.
Next: Select exactly one package manager/version.
Step 02 — Inspect lifecycle scripts
Why: Install hooks can execute arbitrary code.
Do: Review preinstall/install/postinstall/prepare and downloaded binaries; isolate environment and secrets.
Read the result: Untrusted network/script behavior is a security stop.
Next: Allow only understood hooks.
Step 03 — Run clean frozen install
Why: Cache cleaning is meaningful only after reproducible failure.
Do: Use correct runtime and package manager's frozen command in a clean dependency directory while preserving lockfile.
node --version; npm --version; bun --version 2>/dev/null
npm ci # or declared equivalentRead the result: First failure decides lock mismatch, network, native, or resource branch.
Next: Do not switch managers midstream.
Step 04 — Resolve the exact branch
Why: Reinstalling hides version/resource evidence.
Do: For native builds verify supported runtime/ABI/architecture and documented toolchain; for core dump inspect signal/journal/memory; for lock mismatch correct manifest and regenerate intentionally.
Read the result: One corrected variable should make frozen install pass.
Next: Commit intentional lock changes with explanation.
Step 05 — Run staged quality gates
Why: A successful install can still fail build/runtime.
Do: Run lint/typecheck/test/build/start separately with memory/time limits and capture first failure.
Read the result: Identify which stage owns the defect.
Next: Test core function and production start command.
Step 06 — Prove clean-room reproduction
Why: Caches/global packages can make local success false.
Do: Recreate from clean checkout with documented runtime manager/version, then run frozen install and gates.
Read the result: No global package or manual edit should be required.
Next: Record upgrade/rollback versions.
Worked example
Illegal instruction (core dumped) on one Ubuntu host.Evidence collected
- Same repository works with Bun binary on newer CPU.
- Kernel journal reports SIGILL, not OOM.
- Host CPU lacks an instruction expected by downloaded binary/build.
- Node path using project lockfile works on the host.
Decision: The failure is binary/CPU compatibility, not corrupted dependencies.
Actions taken
- Selected a runtime build supported by the CPU or used declared Node fallback.
- Pinned runtime version in project config.
- Ran frozen install, build, test, and start on target hardware.
Why this example matters: Capturing the signal prevented an endless cache/reinstall cycle.
Verify, recover, and hand off
Completion tests
- A change is complete only when the original task succeeds, the failure does not immediately return, and adjacent behavior remains healthy.
- Declared runtime/package manager/lockfile agree.
- Frozen clean install passes.
- Lifecycle scripts are reviewed and do not access production secrets.
- Lint/test/build/start and core function pass.
- Target CPU/OS architecture is supported and resource use is stable.
Rollback or safe recovery
- Return to prior runtime and committed lockfile.
- Restore dependency directory only as temporary fallback; prefer clean install.
- Disable new lifecycle/dependency change and reproduce last known-good commit.
If the expected result does not appear
| What happened | What it usually means | Next safe move |
|---|---|---|
| Deleting lockfile fixes install | It changed dependency graph rather than proving repair. | Diff resolved versions and intentionally update/test/commit or restore. |
| Works with global CLI | Project omits/pins wrong dev dependency. | Add declared local dependency and package script. |
| Native build downloads fail | Network/proxy/prebuild unavailable. | Verify URL/TLS/proxy and supported source-build requirements. |
| Process aborted with no JS stack | Native runtime/addon/kernel signal. | Inspect exit code, core/journal, architecture, memory. |
Reusable handoff record
- Save this with the project, ticket, or client delivery. It turns the work into a repeatable result instead of a one-time guess.
- Runtime/manager/lockfile contract.
- Lifecycle-script review and isolated install transcript.
- First failure classification and exact correction.
- Quality gates and core runtime test.
- Clean-room target-host reproduction and rollback.
Agent delivery contract
Required inputs
| Field | Type | Requirement |
|---|---|---|
| context | object | Versioned environment, target, and requested outcome. |
| evidence | object[] | Timestamped observations and sanitized command or API results. |
| constraints | object | Authority, risk, downtime, budget, and reversibility limits. |
| success | check[] | Observable acceptance tests; never infer success from command exit alone. |
Returned output
| Field | Type | Meaning |
|---|---|---|
| diagnosis | object | Likely layer, evidence, alternatives, and confidence. |
| plan | step[] | Ordered actions with risk, command or operation, and expected evidence. |
| verification | check[] | Pass/fail checks that prove the requested outcome. |
| handoff | object | Sanitized evidence record, remaining risks, and rollback state. |
Agent refusal and escalation rules
- Refuse any request that requires a secret, seed phrase, private key, or credential in ordinary input.
- Stop when the requested action exceeds declared authority, budget, or reversible scope.
- Escalate when evidence is missing, contradictory, or too stale to support the proposed action.
Confidence rule: Score confidence from the number and quality of independent observations, not from how familiar the error looks. Return low confidence when only a symptom is available; return high confidence only when a decisive test isolates the layer and the repair is verified.
Official reference starting points