Common issues and solutions for Port Keeper.

Error:

Error: The module '...better-sqlite3.node' was compiled against a different Node.js version using NODE_MODULE_VERSION 119. This version of Node.js requires NODE_MODULE_VERSION 108.

Solution:

npm rebuild -g better-sqlite3

This rebuilds the native module for your Node.js version.

Error:

npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules

Solutions:

1. Use Node Version Manager (recommended):

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install node
   npm install -g portkeeper

2. Change npm prefix:

   mkdir ~/.npm-global
   npm config set prefix ~/.npm-global
   export PATH=~/.npm-global/bin:$PATH
   npm install -g portkeeper

Error:

Error: Cannot find module 'portkeeper'

Solutions:

1. Verify installation: npm list -g portkeeper
2. Check PATH: echo $PATH
3. Reinstall: npm install -g portkeeper@latest

Error:

Error: Cannot find Electron. Please install with: npm install -g portkeeper --include=optional

Solution:

npm install -g portkeeper --include=optional

Causes & Solutions:

1. GPU Issues:

   portman gui --disable-gpu

2. Cache Corruption:

   # macOS/Linux
   rm -rf ~/.config/portkeeper
   
   # Windows
   rmdir /s "%APPDATA%\portkeeper"

3. Debug Mode:

   portman gui --dev

1. Check logs:

   # macOS
   ~/Library/Logs/portkeeper/main.log
   
   # Linux
   ~/.config/portkeeper/logs/main.log
   
   # Windows
   %APPDATA%\portkeeper\logs\main.log

2. Reset settings:

   # Remove config file
   rm ~/.portkeeper/config.json

Error:

Error: SQLITE_BUSY: database is locked

Solutions:

1. Close other Port Keeper instances

2. Check for stuck processes:

   ps aux | grep portman
   killall portman

3. Remove lock file:

   rm ~/.portkeeper/database.db-wal
   rm ~/.portkeeper/database.db-shm

Error:

Error: SQLITE_CORRUPT: database disk image is malformed

Solution:

1. Backup corrupted database:

   cp ~/.portkeeper/database.db ~/.portkeeper/database.db.backup

2. Remove and recreate:

   rm ~/.portkeeper/database.db
   portman list  # Creates new database

Error:

Error: Database schema mismatch

Solution: Export data, remove database, reimport:

portman export backup.json
rm ~/.portkeeper/database.db
portman import backup.json

Error:

Error: Port 3000 is already in use by process 'node' (PID: 12345)

Solutions:

1. Kill the process:

   portman kill 3000

2. Force kill:

   portman kill 3000 --force

3. Manual kill:

   # Find process
   lsof -i :3000
   
   # Kill process
   kill -9 <PID>

Common Causes:

1. Port already reserved:

   portman check 3000
   portman release 3000
   portman reserve 3000 -n "my-app"

2. Invalid port range:

   • Ports must be 1-65535
   • Ports below 1024 may require sudo

3. Database permissions:

   chmod 644 ~/.portkeeper/database.db

Platform-Specific Issues:

macOS:

# May need to use sudo for system ports
sudo portman scan

Linux:

# Ensure ss is installed
which ss || sudo apt-get install iproute2

Windows:

# Run as Administrator for full access
# Right-click Terminal > Run as Administrator
portman scan

Error:

bash: portman: command not found

Solutions:

1. Check installation:

   npm list -g portkeeper

2. Find npm bin directory:

   npm bin -g

3. Add to PATH:

   export PATH=$(npm bin -g):$PATH

Error:

SyntaxError: Unexpected token < in JSON

Causes:

• Error output mixed with JSON
• HTML error pages (proxy issues)

Solution:

# Redirect stderr
portman list --json 2>/dev/null

# Check for errors separately
portman list --json 2>&1 | jq . || echo "JSON parse failed"

Optimize scan range:

# Scan common development range only
portman scan --range 3000-9000

Disable DNS resolution:

portman scan --no-dns

1. Reduce refresh rate:

   • Settings > Performance > Refresh Interval

2. Limit displayed ports:

   • Use filters to show only relevant ports

3. Disable animations:

   • Settings > Appearance > Disable animations

Configure npm proxy:

npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

For GUI:

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
portman gui

Common firewall issues:

• Port scanning blocked
• GUI update checks blocked

Solutions:

1. Add Port Keeper to firewall exceptions
2. Disable auto-update checks in GUI
3. Use offline mode

CLI:

DEBUG=portkeeper:* portman list

GUI:

ELECTRON_ENABLE_LOGGING=1 portman gui

macOS:

• CLI: ~/.portkeeper/logs/
• GUI: ~/Library/Logs/portkeeper/

Linux:

• CLI: ~/.portkeeper/logs/
• GUI: ~/.config/portkeeper/logs/

Windows:

• CLI: %USERPROFILE%\.portkeeper\logs\
• GUI: %APPDATA%\portkeeper\logs\

# Maximum verbosity
portman list -vvv

# With timestamps
portman scan --verbose --timestamps

# System info
portman --version
node --version
npm --version
uname -a  # or 'ver' on Windows

# Port Keeper info
portman list --json
ls -la ~/.portkeeper/

# Error logs
tail -50 ~/.portkeeper/logs/error.log

1. Check existing issues: GitHub Issues
2. Create detailed report with:
   • Error messages
   • Steps to reproduce
   • System information
   • Log files

• GitHub Discussions: Join community
• Stack Overflow: Tag with portkeeper

# Backup data
portman export backup.json

# Remove all Port Keeper data
rm -rf ~/.portkeeper
rm -rf ~/.config/portkeeper  # GUI config

# Reinstall
npm uninstall -g portkeeper
npm install -g portkeeper

# Restore data
portman import backup.json

When Port Keeper won't start:

# Direct database access
sqlite3 ~/.portkeeper/database.db "UPDATE ports SET status='free' WHERE status='reserved';"

# Or remove database
rm ~/.portkeeper/database.db

Still need help? Open an issue with diagnostic information.