Troubleshooting

This page documents ElastOS v1 (PC2), the proof of concept. ElastOS v2 is the current system. To install it, see Install ElastOS. To see how the stages fit together, see ElastOS in stages.

Common issues and solutions for PC2.

Installation Issues

Node.js Version Error

Error: “Node.js version 18+ required”

Solution:

# Check version
node --version
 
# Install Node.js 20
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”

Solution:

# Clear cache
npm cache clean --force
 
# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Permission Denied

Error: “EACCES: permission denied”

Solution:

# Fix npm permissions
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”

Solution:

# Find process using port
lsof -i :4200
 
# Kill it
kill -9 <PID>
 
# Or use different port
PORT=4300 npm start

Database Locked

Error: “SQLITE_BUSY: database is locked”

Solution:

# Stop all node processes
pkill -f node
 
# Restart
npm start

Missing Identity

Error: “Identity file not found”

Solution:

  1. Delete the data directory
  2. Restart PC2
  3. Complete setup wizard again
rm -rf data/identity
npm start

Authentication Issues

Wallet Won’t Connect

Symptoms: Click “Connect Wallet” but nothing happens

Solutions:

  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

Symptoms: Suddenly logged out

Solutions:

  1. Connect wallet again
  2. Check server time is correct
  3. Increase session duration in config
{
  "session": {
    "expiryDays": 30
  }
}

Signature Rejected

Symptoms: Wallet popup appears but login fails

Solutions:

  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

Symptoms: Works locally but not remotely

Solutions:

  1. Check firewall:

    ufw allow 4200
    ufw status
  2. Check super node registration:

    curl http://localhost:4200/api/boson/status
  3. Register with gateway:

    curl -X POST https://69.164.241.210/api/gateway/register \
      -H "Content-Type: application/json" \
      -d '{"subdomain": "yourname", "endpoint": "http://YOUR_IP:4200"}'

Active Proxy Not Connecting

Symptoms: NAT traversal not working

Solutions:

  1. Check outbound TCP to port 8090:

    nc -vz 69.164.241.210 8090
  2. Verify identity exists:

    cat data/identity/identity.json
  3. Check proxy status:

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

SSL Certificate Error

Symptoms: “Your connection is not private”

Solutions:

  1. Wait for Let’s Encrypt propagation (up to 30 min)
  2. Check DNS is correct
  3. For custom domain, verify Caddy is running:
    systemctl status caddy
    journalctl -u caddy -n 50

AI Issues

Ollama Not Working

Error: “Connection refused to localhost:11434”

Solutions:

  1. Install Ollama:

    curl -fsSL https://ollama.com/install.sh | sh
  2. Start Ollama:

    ollama serve
  3. Pull a model:

    ollama pull deepseek-r1:7b

Cloud AI Not Responding

Error: “API key invalid” or timeout

Solutions:

  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

Symptoms: Incomplete responses

Solutions:

  1. Try smaller model
  2. Reduce max tokens in request
  3. Check server memory:
    free -m

File Issues

Upload Fails

Error: “File too large”

Solutions:

  1. Check file size limit in config:

    {
      "storage": {
        "maxFileSize": 209715200
      }
    }
  2. Check disk space:

    df -h

Files Not Syncing

Symptoms: Changes don’t appear on other devices

Solutions:

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

Update Issues

Update Stuck

Symptoms: Progress modal hangs

Solutions:

  1. Check server logs:

    journalctl -u pc2-node -f
  2. Manually complete update:

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

Build Fails During Update

Symptoms: “npm ERR!” during update

Solutions:

  1. Check disk space:

    df -h
  2. Check memory:

    free -m
  3. Try manual update with more detail:

    npm install --verbose

Performance Issues

Slow File Operations

Solutions:

  1. Use SSD storage
  2. Check IPFS compaction:
    # May need to rebuild IPFS repo
    rm -rf data/ipfs
    # Restart node

High Memory Usage

Solutions:

  1. Reduce AI model size
  2. Enable swap:
    sudo fallocate -l 2G /swapfile
    sudo chmod 600 /swapfile
    sudo mkswap /swapfile
    sudo swapon /swapfile

High CPU Usage

Solutions:

  1. Check for runaway processes:

    top
  2. Restart the service:

    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: github.com/Elacity/pc2.net/issues

  3. Open new issue with:

    • PC2 version
    • Operating system
    • Error message
    • Steps to reproduce
  4. Community support:

Include your server logs when asking for help—they contain crucial debugging information.

© 2026 Elacity Labs. ELASTOS® is a registered trademark of Elastos DAO. ElastOS is open source under the MIT licence.