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

​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

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