Troubleshooting Guide

Getting Help

Before diving into troubleshooting, here are the best ways to get help:

Discord Community

Join the community for real-time help and discussions

GitHub Issues

Report bugs and request features

Quick Diagnostics

Run these commands to quickly diagnose common issues:

# Check if Portal is running
openportal list

# Check if OpenCode is installed
which opencode

# Check Bun version (recommended: latest)
bun --version

# Check available ports
lsof -i :3000
lsof -i :4000

# Check system resources
free -h
df -h

Installation Issues

Command not found: openportal

Symptom: Shell can’t find the openportal commandSolutions:

Verify installation:
```
bun pm ls -g | grep openportal
```
Reinstall globally:
```
bun install -g openportal
```

Check Bun global bin path:

echo $PATH | grep .bun

If not present, add to your shell profile:

# For bash (~/.bashrc)
export PATH="$HOME/.bun/bin:$PATH"

# For zsh (~/.zshrc)
export PATH="$HOME/.bun/bin:$PATH"

# Reload shell
source ~/.bashrc  # or ~/.zshrc

Use bunx instead:
```
bunx openportal
```

Command not found: opencode

Symptom: Portal can’t find OpenCode installationSolution: Install OpenCode:

# Using Bun
bun install -g opencode

# Or using Homebrew (macOS)
brew install sst/tap/opencode

# Verify installation
which opencode
opencode --version

Installation fails with permission errors

Symptom: EACCES or permission denied errors during installSolutions:

Don’t use sudo with Bun:

# Wrong
sudo bun install -g openportal

# Correct
bun install -g openportal

Fix Bun permissions:
```
chown -R $USER ~/.bun
```

Reinstall Bun:

curl -fsSL https://bun.sh/install | bash

Node.js compatibility issues

Symptom: Errors when running with Node.js instead of BunSolution:

OpenPortal works best with Bun. Node.js may have rough edges.

Install and use Bun:

curl -fsSL https://bun.sh/install | bash
bun install -g openportal

If you must use Node.js:

npm install -g openportal
# May encounter issues - Bun is recommended

Startup Issues

Portal won't start - Port already in use

Symptom: Error message about port 3000 or 4000 being busySolutions:

Let Portal auto-find ports:

openportal
# Will automatically use 3001, 3002, etc. if 3000 is busy

Specify different ports:

openportal --port 3010 --opencode-port 4010

Find what’s using the port:

lsof -i :3000
# Kill the process if safe
kill <PID>

Stop existing Portal instances:
```
openportal stop --all
```

OpenCode server fails to start

Symptom: Web UI loads but can’t connect to OpenCode serverDebug steps:

Check if OpenCode port is accessible:
```
curl http://localhost:4000
```
Try starting OpenCode manually:
```
opencode --port 4000
```
Look for error messages in the output.

Check OpenCode logs:

ls ~/.config/opencode/logs/
tail -f ~/.config/opencode/logs/latest.log

Verify working directory exists:
```
pwd
ls -la
```
Check disk space:
```
df -h .
```

Portal starts but shows blank page

Symptom: Browser shows empty white page or loading foreverSolutions:

Hard refresh the page:
- Chrome/Firefox: Ctrl+Shift+R (Cmd+Shift+R on Mac)
- Safari: Cmd+Option+R
Clear browser cache:
- Chrome: Settings > Privacy > Clear browsing data
- Firefox: Preferences > Privacy > Clear Data
- Safari: Preferences > Privacy > Manage Website Data
Check browser console for errors:
- Open DevTools: F12 or Ctrl+Shift+I
- Look for errors in Console tab

Try different browser:

# Test in another browser to isolate issue

Check if server is actually responding:

curl http://localhost:3000
# Should return HTML

Can't access Portal from other machines

Symptom: Portal works on localhost but not from other devicesSolutions:

Bind to all interfaces:
```
openportal --hostname 0.0.0.0
```

Check firewall rules:

# Ubuntu/Debian
sudo ufw status
sudo ufw allow 3000/tcp

# CentOS/RHEL
sudo firewall-cmd --list-ports
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --reload

Verify Portal is listening on 0.0.0.0:

netstat -tlnp | grep 3000
# Should show 0.0.0.0:3000, not 127.0.0.1:3000

Test connectivity:

# From another machine
ping your-server-ip
curl http://your-server-ip:3000

Connection Issues

Lost connection to OpenCode server

Symptom: “Connection lost” or “Reconnecting…” messagesSolutions:

Check if OpenCode server is running:
```
openportal list
ps aux | grep opencode
```
Restart Portal:
```
openportal stop
openportal
```

Check server logs:

tail -f ~/.config/opencode/logs/latest.log

Verify network connectivity:
```
curl http://localhost:4000
```
Check for resource issues:
```
top
free -h
```

Slow or laggy responses

Symptom: Portal feels sluggish, AI responses take very longDebug steps:

Check system resources:

htop
# Look for high CPU or memory usage

Check disk I/O:
```
iostat -x 1
```

Verify network latency (for remote access):

ping your-server
traceroute your-server

Check OpenCode model settings:
- Larger models (GPT-4, Claude Opus) are slower
- Try a faster model for testing

Restart with clean state:

openportal stop
openportal clean
openportal

WebSocket connection fails

Symptom: Real-time updates not working, need to refresh manuallySolutions:

Check for reverse proxy issues: If using Nginx, ensure WebSocket headers are configured:

location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
}

Check firewall doesn’t block WebSockets:

# Test WebSocket connection
wscat -c ws://localhost:3000

Browser extensions interfering:
- Try in incognito/private mode
- Disable ad blockers and privacy extensions

Session Issues

Can't create new session

Symptom: Create session button doesn’t work or errors outSolutions:

Check OpenCode server is accessible:
```
curl http://localhost:4000/sessions
```

Verify permissions on OpenCode config directory:

ls -la ~/.config/opencode/
chmod -R u+rw ~/.config/opencode/

Check disk space:
```
df -h ~
```

Try creating session via OpenCode CLI:

opencode
# If this works, issue is with Portal
# If this fails, issue is with OpenCode

Sessions not showing up

Symptom: Created sessions but they don’t appear in the listDebug:

Check OpenCode sessions directory:
```
ls ~/.config/opencode/sessions/
```
Verify API is returning sessions:
```
curl http://localhost:4000/sessions
```
Refresh the browser:
- F5 or Ctrl+R
Check browser console for errors:
- F12 > Console tab

Can't delete sessions

Symptom: Delete button doesn’t work or session reappearsSolutions:

Check file permissions:

ls -la ~/.config/opencode/sessions/
chmod -R u+rw ~/.config/opencode/sessions/

Delete manually:

rm -rf ~/.config/opencode/sessions/<session-id>

Verify not open in another instance:
- Close all OpenCode instances
- Try deleting again

Session messages not loading

Symptom: Open a session but messages don’t appearSolutions:

Check session file exists:

ls ~/.config/opencode/sessions/<session-id>/
cat ~/.config/opencode/sessions/<session-id>/session.json

Verify JSON is valid:

cat ~/.config/opencode/sessions/<session-id>/session.json | jq
# If jq fails, JSON is corrupted

Check browser console:
- F12 > Console > Look for parsing errors
Try opening in official OpenCode CLI:
```
opencode --resume <session-id>
```

Mobile-Specific Issues

Can't access Portal from mobile via Tailscale

Symptom: Portal works on server but not accessible from phoneSolutions:

Verify Tailscale is connected on both devices:

# On server
tailscale status

# On mobile: Check Tailscale app shows "Connected"

Verify Portal bound to 0.0.0.0:

netstat -tlnp | grep 3000
# Should show 0.0.0.0:3000

Test connectivity:

# On mobile (using terminal app)
ping server-name
curl http://server-name:3000

Try IP address instead of hostname:

# On server, get Tailscale IP
tailscale ip -4

# On mobile, use IP directly
http://100.x.x.x:3000

See Tailscale Setup Guide for detailed troubleshooting.

Portal UI not responsive on mobile

Symptom: UI elements too small or not clickable on mobileSolutions:

Hard refresh the page:
- Safari: Pull down to refresh
- Chrome: Menu > Reload
Clear mobile browser cache:
- Safari: Settings > Safari > Clear History and Website Data
- Chrome: Settings > Privacy > Clear browsing data
Try different mobile browser:
- iOS: Safari, Chrome, Firefox
- Android: Chrome, Firefox, Samsung Internet
Check if Desktop mode is enabled:
- Disable “Request Desktop Site”
Report UI issue with screenshots:
- GitHub Issues

Mobile browser keeps disconnecting

Symptom: Connection drops when switching apps or locking screeniOS Solutions:

Settings > Tailscale > Allow unlimited background activity
Disable Low Power Mode while using Portal
Keep Portal tab active (don’t close)

Android Solutions:

Settings > Apps > Tailscale > Battery > Unrestricted
Settings > Apps > Browser > Battery > Unrestricted
Enable “Always-on VPN” in Tailscale settings

Performance Issues

High memory usage

Symptom: Portal or OpenCode consuming excessive RAMSolutions:

Check actual memory usage:

ps aux | grep opencode
ps aux | grep openportal

Limit resources with systemd:

# In service file
[Service]
MemoryLimit=512M

Delete old sessions:

# Clean up old sessions manually
ls ~/.config/opencode/sessions/

Restart Portal regularly:
```
openportal stop
openportal
```
Use lighter AI model:
- Switch from Claude Opus to Sonnet
- Use GPT-3.5 instead of GPT-4

High CPU usage

Symptom: Server CPU constantly high even when idleDebug:

Identify CPU-hungry process:
```
top
# Press 'P' to sort by CPU
```
Check for infinite loops in code:
- Review recent changes
- Check OpenCode logs for errors

Verify no stuck sessions:

openportal list
# Stop stuck instances
openportal stop --all

Check for disk I/O bottleneck:
```
iostat -x 1
```

Slow AI responses

Symptom: AI takes very long to respond or times outFactors:

Model speed varies:
- GPT-4, Claude Opus: Slowest but best quality
- GPT-4 Turbo, Claude Sonnet: Balanced
- GPT-3.5: Fastest but lower quality
API rate limits:
- Check your OpenAI/Anthropic account for rate limits
- Upgrade API tier if needed

Network latency:

# Test API connectivity
curl -I https://api.openai.com
curl -I https://api.anthropic.com

Large context:
- Large codebases take longer to process
- Mention fewer files to reduce context

Check OpenCode logs:

tail -f ~/.config/opencode/logs/latest.log

File Operations

Can't mention files with @

Symptom: File autocomplete doesn’t work or files not foundSolutions:

Verify you’re in correct directory:
```
pwd
ls
```
Check file permissions:
```
ls -la
# Files should be readable
```
Relative vs absolute paths:
- Use relative paths: @src/index.ts
- Not absolute: ~/project/src/index.ts
File indexing:
- OpenCode indexes files on start
- Restart if new files not appearing

Large files causing issues

Symptom: Portal hangs when mentioning large filesWorkarounds:

Check file size:
```
ls -lh path/to/file
```
Avoid mentioning very large files:
- Binary files
- Generated files (build output, node_modules)
- Database dumps
Use .gitignore patterns:
- OpenCode respects .gitignore
- Add large files to .gitignore
Mention specific sections: Instead of mentioning entire file, describe the section: “The login function in @auth.ts around line 50”

Data and Configuration

How to reset Portal completely

To start fresh:

# Stop all instances
openportal stop --all

# Clean registry
openportal clean

# Remove Portal config (if exists)
rm -rf ~/.config/openportal/

# Remove OpenCode sessions (WARNING: deletes all sessions)
rm -rf ~/.config/opencode/sessions/

# Reinstall Portal
bun install -g openportal

# Start fresh
openportal

Where is data stored?

Portal stores data in:

Registry: ~/.config/openportal/registry.json
Logs: System logs (check with journalctl if using systemd)

OpenCode stores data in:

Sessions: ~/.config/opencode/sessions/
Config: ~/.config/opencode/config.json
Logs: ~/.config/opencode/logs/

Backup important data:

tar -czf opencode-backup.tar.gz ~/.config/opencode/sessions/

How to migrate to new server

Migration steps:

On old server, backup sessions:

tar -czf sessions-backup.tar.gz ~/.config/opencode/sessions/
scp sessions-backup.tar.gz new-server:

On new server, install everything:

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Install OpenCode
bun install -g opencode

# Install Portal
bun install -g openportal

Restore sessions:

mkdir -p ~/.config/opencode
tar -xzf sessions-backup.tar.gz -C ~/

Set up Tailscale: See Tailscale Setup Guide

Start Portal:

cd /path/to/project
openportal --hostname 0.0.0.0

Error Messages

EADDRINUSE: address already in use

Meaning: The port is already occupied by another processFix:

# Find what's using the port
lsof -i :3000

# Kill the process or use different port
openportal --port 3010

ECONNREFUSED: Connection refused

Meaning: Can’t connect to OpenCode serverFix:

# Check if OpenCode is running
ps aux | grep opencode

# Restart Portal
openportal stop
openportal

ENOSPC: no space left on device

Meaning: Disk is fullFix:

# Check disk usage
df -h

# Find large files
du -h --max-depth=1 ~ | sort -hr | head -20

# Clean up old sessions
rm -rf ~/.config/opencode/sessions/old-session-id

# Clean package caches
bun pm cache rm
npm cache clean --force

ETIMEDOUT: Connection timeout

Meaning: Network request took too longFix:

# Check network connectivity
ping 8.8.8.8

# Test API endpoints
curl https://api.openai.com

# Restart network/VPN
# For Tailscale:
sudo systemctl restart tailscaled

Still Having Issues?

Ask on Discord

Get help from the community in real-time

Open GitHub Issue

Report bugs or request features

When asking for help, please include:

Operating system and version
Bun version: bun --version
OpenCode version: opencode --version
Portal version: openportal --version (if available)
Full error message or logs
Steps to reproduce the issue
What you’ve already tried

Gather diagnostic information:

# System info
uname -a
bun --version
opencode --version

# Portal status
openportal list

# Check logs
tail -50 ~/.config/opencode/logs/latest.log

# Network info
netstat -tlnp | grep -E '3000|4000'

# Resource usage
top -b -n 1 | head -20
free -h
df -h

Next Steps

Mobile Access Guide - Access Portal from your phone
Tailscale Setup - Set up secure VPN access
Multiple Projects - Manage multiple Portal instances

Getting Started

Installation

Core Features

CLI Reference

Guides

Getting Help

Discord Community

GitHub Issues

Quick Diagnostics

Installation Issues

Startup Issues

Connection Issues

Session Issues

Mobile-Specific Issues

Performance Issues

File Operations

Data and Configuration

Error Messages

Still Having Issues?

Ask on Discord

Open GitHub Issue

Next Steps

Build docs developers (and LLMs) love

Getting Started

Installation

Core Features

CLI Reference

Guides

​Getting Help

Discord Community

GitHub Issues

​Quick Diagnostics

​Installation Issues

​Startup Issues

​Connection Issues

​Session Issues

​Mobile-Specific Issues

​Performance Issues

​File Operations

​Data and Configuration

​Error Messages

​Still Having Issues?

Ask on Discord

Open GitHub Issue

​Next Steps

Build docs developers (and LLMs) love

Getting Help

Quick Diagnostics

Installation Issues

Startup Issues

Connection Issues

Session Issues

Mobile-Specific Issues

Performance Issues

File Operations

Data and Configuration

Error Messages

Still Having Issues?

Next Steps