Troubleshooting

Common issues and solutions when using Smippo.

Installation Issues

Browser Download Fails

Symptom: Error during npm install -g smippo related to browser download.

Solutions:

  1. Retry the installation:
npm uninstall -g smippo
npm install -g smippo

  1. Check your network connection and proxy settings.

  2. If you're behind a corporate firewall, you may need to configure proxy settings.

Permission Denied

Symptom: EACCES: permission denied during global install.

Solutions:

  1. Use sudo (not recommended):
sudo npm install -g smippo
  1. Configure npm to use a local directory (recommended):
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
npm install -g smippo
  1. Add to your shell profile:
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc

Node.js Version

Symptom: Error: smippo requires Node.js 18 or later

Solution: Update Node.js:

# Using nvm
nvm install 18
nvm use 18

# Or download from nodejs.org

Capture Issues

Page Loads But Content Missing

Symptom: HTML captured but dynamic content is missing.

Solutions:

  1. Increase wait time:
smippo https://example.com --wait-time 5000
  1. Use network idle wait:
smippo https://example.com --wait networkidle
  1. For SPAs, wait longer:
smippo https://spa-app.com --wait-time 10000

Timeout Errors

Symptom: Error: Timeout 30000ms exceeded

Solutions:

  1. Increase timeout:
smippo https://slow-site.com --timeout 60000
  1. Use a faster wait strategy:
smippo https://example.com --wait domcontentloaded
  1. Check if the site is actually slow or blocking automated access.

Rate Limiting / 429 Errors

Symptom: Many 429 Too Many Requests errors.

Solutions:

  1. Reduce workers:
smippo https://example.com --workers 2
  1. Add rate limiting:
smippo https://example.com --rate-limit 2000
  1. Combine both:
smippo https://example.com --workers 1 --rate-limit 3000

Authentication Failures

Symptom: Pages return 401 or redirect to login.

Solutions:

  1. Use cookie-based auth:
smippo https://example.com --cookies cookies.json
  1. Use interactive auth:
smippo https://example.com --capture-auth
  1. Check if cookies have expired.

Blocked by Bot Detection

Symptom: Site returns CAPTCHA or blocks access.

Solutions:

  1. Try a real user agent:
smippo https://example.com --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  1. Use interactive auth to solve CAPTCHA:
smippo https://example.com --capture-auth
  1. Add delays to appear more human:
smippo https://example.com --workers 1 --rate-limit 3000 --wait-time 2000

robots.txt Blocking

Symptom: Pages skipped due to robots.txt.

Solutions:

  1. Ignore robots.txt (use responsibly):
smippo https://example.com --ignore-robots
  1. Check what's blocked:
curl https://example.com/robots.txt

Output Issues

Broken Images

Symptom: Images show as broken in offline view.

Solutions:

  1. Enable external assets:
smippo https://example.com --external-assets
  1. Check if images were filtered:
# Don't exclude images
smippo https://example.com --mime-include "image/*"
  1. Verify the file exists:
ls ./site/example.com/images/

Missing Styles

Symptom: Page looks unstyled.

Solutions:

  1. Capture external CSS:
smippo https://example.com --external-assets
  1. Check CSS was captured:
find ./site -name "*.css"
  1. Verify CSS links are rewritten:
grep 'href.*css' ./site/example.com/index.html

JavaScript Errors

Symptom: Console errors when viewing offline.

Solutions:

  1. For read-only archives, strip JS:
smippo https://example.com --static
  1. Check JS files were captured:
find ./site -name "*.js"
  1. Some JS won't work offline (API calls, etc.) - this is expected.

Links Don't Work

Symptom: Clicking links results in 404.

Solutions:

  1. Use the built-in server:
smippo serve ./site --open
  1. Check link rewriting:
grep 'href=' ./site/example.com/index.html
  1. Ensure pages were captured:
cat ./site/.smippo/manifest.json | grep localPath

Performance Issues

Capture Too Slow

Solutions:

  1. Increase workers:
smippo https://example.com --workers 12
  1. Use faster wait strategy:
smippo https://example.com --wait domcontentloaded
  1. Filter out large files:
smippo https://example.com --max-size 5MB --mime-exclude "video/*"
  1. Disable HAR:
smippo https://example.com --no-har

High Memory Usage

Solutions:

  1. Reduce workers:
smippo https://example.com --workers 4
  1. Filter large files:
smippo https://example.com --max-size 2MB
  1. Disable HAR (can get large):
smippo https://example.com --no-har

Capture Never Finishes

Solutions:

  1. Set limits:
smippo https://example.com --max-pages 500 --max-time 600
  1. Narrow scope:
smippo https://example.com --scope subdomain --stay-in-dir
  1. Check for infinite loops (sites that generate endless pages):
smippo https://example.com --verbose  # Watch for patterns

Server Issues

Port Already in Use

Symptom: Server fails to start on port 8080.

Solutions:

Smippo auto-finds available ports. Or specify one:

smippo serve ./site --port 3000

CORS Errors

Symptom: Browser console shows CORS errors.

Solution: CORS is enabled by default. If you disabled it:

smippo serve ./site  # CORS enabled by default

Files Not Found

Symptom: Server returns 404 for existing files.

Solutions:

  1. Check file paths are correct:
ls ./site/example.com/
  1. Ensure you're serving the right directory:
smippo serve ./site  # Not ./site/example.com

Getting Help

Debug Mode

Run with visible browser to see what's happening:

smippo https://example.com --debug

Verbose Logging

Get detailed output:

smippo https://example.com --verbose --log-file capture.log

Check the HAR File

Open ./site/.smippo/network.har in HAR viewer tools to inspect all requests/responses.

Report Issues

If you've tried these solutions and still have issues:

  1. Run with --debug --verbose
  2. Note your Node.js version (node --version)
  3. Note your OS
  4. Include the error message
  5. Open an issue on GitHub

Next Steps

Was this page helpful?