npm postinstall script hang fix

npm postinstall script hang fix | Generated by AI

Home 2026.04

Question: Why is my npm install getting stuck after running postinstall scripts for packages like fsevents, better-sqlite3, @askjo/camoufox-browser, agent-browser, and geckodriver?

Answer:

Your npm installation appears to be hanging (stuck with the spinner ⠇ ⠋ ⠧) right after several postinstall scripts have finished. This is a common issue, especially on macOS, and here are the most likely causes and fixes:

Most Common Reasons for the Hang:

@askjo/camoufox-browser postinstall script
The command npx camoufox-js fetch || true is likely the culprit.
- This script probably downloads a large browser binary (Camoufox is a Firefox-based browser for automation/testing).
- Downloads can be very slow, fail silently, or get stuck due to network issues, firewall, VPN, or rate limiting.
- Even though it has || true, the underlying process may still be running in the background or hanging.
Network-related problems
- Slow or unstable internet connection while fetching large files (browser binaries, drivers, etc.).
- Corporate/school firewall or proxy blocking the download.
- npm registry or GitHub release mirrors being slow.
Other postinstall scripts
- fsevents failed (expected on non-macOS or sometimes on macOS with node-gyp issues), but it’s marked as optional so it usually doesn’t block.
- better-sqlite3, agent-browser, and geckodriver completed successfully (code: 0).
- However, some scripts can spawn background processes that keep npm waiting.
npm itself being slow or in a bad state
- Large node_modules folder or many dependencies.
- npm cache corruption.
- Running out of disk space or memory during extraction/install.

How to Fix It:

Immediate actions (try in order):

Wait a bit longer
The download for camoufox might just be slow. Let it run for 5–10 more minutes before killing it.
Cancel and retry with more visibility
Press Ctrl + C to stop, then run:
```
npm install --loglevel=verbose
```
This will show more detailed output so you can see exactly which part is hanging.
Skip or fix the problematic postinstall
Try installing while skipping optional dependencies or scripts:
```
npm install --ignore-scripts
```
Then manually run the important scripts if needed:
```
npx camoufox-js fetch
```
Or force skip the camoufox fetch temporarily:
```
npm install --ignore-scripts
```

Clear cache and clean install (recommended if it keeps failing):

rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Check network and resources
- Make sure you have a stable, fast internet connection.
- Check available disk space: df -h
- Monitor network activity or use a different network/VPN.
Update npm and Node.js
```
npm install -g npm@latest
```
Also consider updating your Node version if it’s very old.
Specific fix for camoufox-browser
If the fetch keeps hanging, you can try running it manually with more output:
```
npx camoufox-js fetch --verbose
```
(Check the package documentation for exact flags.)

Additional Tips:

This kind of hanging often happens with browser automation packages (puppeteer, playwright, geckodriver, camoufox, etc.) because they download large binaries (~100MB+).
If you’re on macOS (as the path suggests /Users/lzwjava/...), fsevents failing is normal if you’re not on a real Mac or if Xcode command line tools are missing.
For better-sqlite3, make sure you have Python and build tools installed if it ever fails in the future.

Try the --loglevel=verbose version first so you can see what’s actually happening right now.

If you share the full verbose output after it gets stuck again, I can help pinpoint the exact cause more accurately.

References:

None

Back Donate