Skip to main content
HOW-TO

PC2 Troubleshooting

Common issues and solutions for PC2.

Installation Issues​

Node.js Version Error​

Error: "Node.js version 18+ required"

node --version

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

npm Install Fails​

Error: "npm ERR! code ENOENT"

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

Permission Denied​

Error: "EACCES: permission denied"

sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Startup Issues​

Port Already in Use​

Error: "EADDRINUSE: address already in use :::4200"

lsof -i :4200
kill -9 <PID>

Or use a different port: PORT=4300 npm start

Database Locked​

Error: "SQLITE_BUSY: database is locked"

pkill -f node
npm start

Missing Identity​

Error: "Identity file not found"

rm -rf data/identity
npm start

Complete the setup wizard again.

Authentication Issues​

Wallet Won't Connect​

  1. Check browser console for errors (F12)
  2. Try different browser
  3. Disable VPN (can block WalletConnect)
  4. Clear browser cache
  5. Try different wallet (MetaMask vs WalletConnect)

Session Expired​

Connect wallet again. Increase session duration in config:

{
  "session": {
    "expiryDays": 30
  }
}

Signature Rejected​

  1. Click "Sign" in wallet popup (don't reject)
  2. Check wallet is on correct network
  3. Try disconnecting and reconnecting wallet

Connection Issues​

Can't Access from Internet​

ufw allow 4200
ufw status

curl http://localhost:4200/api/boson/status

Active Proxy Not Connecting​

nc -vz 198.51.100.1 8090

cat data/identity/identity.json

curl http://localhost:4200/api/boson/status

SSL Certificate Error​

For custom domain, verify Caddy is running:

systemctl status caddy
journalctl -u caddy -n 50

Wait up to 30 minutes for Let's Encrypt propagation. Check DNS is correct.

AI Issues​

Ollama Not Working​

Error: "Connection refused to localhost:11434"

curl -fsSL https://ollama.com/install.sh | sh
ollama serve
ollama pull deepseek-r1:7b

Cloud AI Not Responding​

  1. Verify API key is correct
  2. Check API key has credits/quota
  3. Try regenerating API key
  4. Check provider status page

AI Response Cuts Off​

Check server memory (free -m), try a smaller model, or reduce max tokens in request.

File Issues​

Upload Fails​

Error: "File too large"

Increase in config:

{
  "storage": {
    "maxFileSize": 209715200
  }
}

Check disk space: df -h

Files Not Syncing​

  1. Check WebSocket connection (browser console)
  2. Refresh the page
  3. Check server logs for errors

Update Issues​

Update Stuck​

journalctl -u pc2-node -f

cd /path/to/pc2-node
git pull origin main
npm install
npm run build
systemctl restart pc2-node

Build Fails During Update​

Check disk space (df -h), memory (free -m), and run npm install --verbose for more detail.

Performance Issues​

Slow File Operations​

Rebuild IPFS repo:

rm -rf data/ipfs
# Restart node

Use SSD storage for best performance.

High Memory Usage​

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Reduce AI model size if running Ollama.

High CPU Usage​

top
systemctl restart pc2-node

Getting Help​

If none of these solutions work:

  1. Check logs: journalctl -u pc2-node -n 100
  2. Search GitHub Issues
  3. Open a new issue with: PC2 version, operating system, error message, steps to reproduce
  4. Community support: Telegram