Node, npm and Bun Repair Guide

The result you are building

Finished Result:

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.

Stop Before Proceeding:

Stop before running unknown install/postinstall scripts with production credentials or SSH agents available. Inspect scripts and use an isolated environment.

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

  Start with the row that most closely matches the evidence. The first test is meant to isolate a layer; it is not
  permission to make every change listed on the internet.

    Evidence                  Likely layer       First decisive check           What the result means

    Frozen install rejects    Manifest/lock      Use declared package manager   Repository committed inconsistent
    lockfile                  mismatch           and inspect diff               dependency state.

    Unsupported               Runtime            Compare                        Use project version; do not patch
    engine/syntax             version            engines/packageManager and     dependencies yet.
                                                 CI

    node-gyp/native build     ABI/toolchain      Read first compiler/download   Missing supported prebuild, headers,
    fails                                        error                          compiler, Python, or architecture.

    Killed/core dumped        Resource/runti     Exit signal, journal,          OOM, illegal instruction, corrupt binary, or
                              me                 RAM/swap/disk, architecture    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.

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.

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.

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 equivalent

Read the result: First failure decides lock mismatch, network, native, or resource branch.

Next: Do not switch managers midstream.

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.

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.

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

Starting Problem:

Bun exits 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.

Proof Of Completion:

No SIGILL; clean-room run passes on target architecture; runtime requirement is documented.

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 Diff resolved versions and intentionally than proving repair. update/test/commit or restore.

Works with global CLI Project omits/pins wrong dev Add declared local dependency and package dependency. 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

• https://docs.npmjs.com/cli/v11/commands/npm-ci
• https://nodejs.org/en/download
• https://bun.sh/docs/installation