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 nodejsnpm 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 installPermission Denied
Error: “EACCES: permission denied”
Solution:
# Fix npm permissions
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modulesStartup 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 startDatabase Locked
Error: “SQLITE_BUSY: database is locked”
Solution:
# Stop all node processes
pkill -f node
# Restart
npm startMissing Identity
Error: “Identity file not found”
Solution:
- Delete the data directory
- Restart PC2
- Complete setup wizard again
rm -rf data/identity
npm startAuthentication Issues
Wallet Won’t Connect
Symptoms: Click “Connect Wallet” but nothing happens
Solutions:
- Check browser console for errors (F12)
- Try different browser
- Disable VPN (can block WalletConnect)
- Clear browser cache
- Try different wallet (MetaMask vs WalletConnect)
Session Expired
Symptoms: Suddenly logged out
Solutions:
- Connect wallet again
- Check server time is correct
- Increase session duration in config
{
"session": {
"expiryDays": 30
}
}Signature Rejected
Symptoms: Wallet popup appears but login fails
Solutions:
- Click “Sign” in wallet popup (don’t reject)
- Check wallet is on correct network
- Try disconnecting and reconnecting wallet
Connection Issues
Can’t Access from Internet
Symptoms: Works locally but not remotely
Solutions:
-
Check firewall:
ufw allow 4200 ufw status -
Check super node registration:
curl http://localhost:4200/api/boson/status -
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:
-
Check outbound TCP to port 8090:
nc -vz 69.164.241.210 8090 -
Verify identity exists:
cat data/identity/identity.json -
Check proxy status:
curl http://localhost:4200/api/boson/status
SSL Certificate Error
Symptoms: “Your connection is not private”
Solutions:
- Wait for Let’s Encrypt propagation (up to 30 min)
- Check DNS is correct
- 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:
-
Install Ollama:
curl -fsSL https://ollama.com/install.sh | sh -
Start Ollama:
ollama serve -
Pull a model:
ollama pull deepseek-r1:7b
Cloud AI Not Responding
Error: “API key invalid” or timeout
Solutions:
- Verify API key is correct
- Check API key has credits/quota
- Try regenerating API key
- Check provider status page
AI Response Cuts Off
Symptoms: Incomplete responses
Solutions:
- Try smaller model
- Reduce max tokens in request
- Check server memory:
free -m
File Issues
Upload Fails
Error: “File too large”
Solutions:
-
Check file size limit in config:
{ "storage": { "maxFileSize": 209715200 } } -
Check disk space:
df -h
Files Not Syncing
Symptoms: Changes don’t appear on other devices
Solutions:
- Check WebSocket connection (browser console)
- Refresh the page
- Check server logs for errors
Update Issues
Update Stuck
Symptoms: Progress modal hangs
Solutions:
-
Check server logs:
journalctl -u pc2-node -f -
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:
-
Check disk space:
df -h -
Check memory:
free -m -
Try manual update with more detail:
npm install --verbose
Performance Issues
Slow File Operations
Solutions:
- Use SSD storage
- Check IPFS compaction:
# May need to rebuild IPFS repo rm -rf data/ipfs # Restart node
High Memory Usage
Solutions:
- Reduce AI model size
- Enable swap:
sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile
High CPU Usage
Solutions:
-
Check for runaway processes:
top -
Restart the service:
systemctl restart pc2-node
Getting Help
If none of these solutions work:
-
Check logs:
journalctl -u pc2-node -n 100 -
Search GitHub Issues: github.com/Elacity/pc2.net/issues
-
Open new issue with:
- PC2 version
- Operating system
- Error message
- Steps to reproduce
-
Community support:
- Telegram: t.me/elastos
Include your server logs when asking for help—they contain crucial debugging information.