Troubleshooting

Connection Issues

Can't Pair Devices

Symptom: QR code scan fails or pairing times out.

Solutions:

1. Internet access: Ensure both devices have internet connectivity
2. Fresh code: QR codes expire after 5 minutes—run arc0 pair again
3. Camera permissions: Ensure the app has camera access
4. CLI running: Verify Arc0 CLI is running

# Check CLI status
arc0 status

# Generate new pairing code
arc0 pair

Connection Drops

Symptom: App shows "Disconnected" intermittently.

Solutions:

1. Network stability: Switch to a more stable network
2. Battery optimization: Disable battery optimization for Arc0 (Android)
3. Background app refresh: Enable for Arc0 (iOS)
4. Restart CLI: Stop and restart Arc0 CLI

# Restart CLI
arc0 stop
arc0 start

Tunnel Connection Issues

Symptom: WebSocket tunnel not connecting.

Solutions:

1. Check internet: Both devices need internet access
2. Firewall: Ensure outbound WebSocket connections aren't blocked
3. Restart: Restart both CLI and mobile app
4. Re-pair: Try pairing again with a fresh QR code

Notification Issues

Not Receiving Notifications

Symptom: Agent asks questions but no push notification.

Solutions:

1. Check app permissions: Ensure notifications are enabled in device settings
2. Check CLI config: Verify notifications are enabled

notifications:
  enabled: true
  on_question: true

3. Focus mode: Check iOS Focus or Android DND isn't blocking Arc0
4. Connection: Verify app shows "Connected" status
5. Battery saver: Disable battery optimization (Android)

Delayed Notifications

Symptom: Notifications arrive late.

Solutions:

1. Background refresh: Enable background app refresh
2. Battery optimization: Disable (Android)
3. Network: Check for high latency networks
4. Debounce setting: Reduce notification debounce time

performance:
  notification_debounce: 500 # ms, default is 1000

Too Many Notifications

Symptom: Getting notifications for everything.

Solutions:

1. Filter notification types:

notifications:
  on_question: true
  on_error: true
  on_diff: false # Disable diff notifications
  on_complete: false # Disable completion notifications

2. Set quiet hours:

notifications:
  quiet_hours:
    enabled: true
    start: '22:00'
    end: '08:00'

Agent Issues

Agent Not Detected

Symptom: Running agent in tmux but nothing shows in app.

Solutions:

1. Verify tmux: Agent must be running inside a tmux session
2. Check CLI is running: Arc0 CLI must be active
3. Custom pattern: For unknown agents, add detection pattern

agents:
  - name: 'my-agent'
    pattern: 'my-agent-binary'

4. Check logs:

arc0 logs --tail 50

Questions Not Detected

Symptom: Agent asks questions but Arc0 doesn't notify.

Solutions:

1. Check question patterns: Arc0 may not recognize the format
2. Add custom patterns:

agents:
  - name: 'claude'
    question_patterns:
      - "\\?$"
      - '^Should I'
      - '^Do you want'
      - '^Please (confirm|choose)'

3. Enable verbose logging:

arc0 start --log-level debug

Diffs Not Showing

Symptom: Agent modifies files but diff viewer is empty.

Solutions:

1. Check diff format: Arc0 expects standard unified diff format
2. Add diff patterns:

agents:
  - name: 'my-agent'
    diff_patterns:
      - '^diff --git'
      - "^\\+\\+\\+ "
      - '^--- '

App Issues

App Crashes

Symptom: Arc0 app closes unexpectedly.

Solutions:

1. Update app: Ensure you have the latest version
2. Clear cache: Settings → Clear Cache
3. Reinstall: Delete and reinstall the app
4. Report bug: Contact support with crash details

Diff Viewer Slow

Symptom: Large diffs take long to render.

Solutions:

1. Reduce context lines:

   Settings → Diff Viewer → Context Lines → 3

2. Use unified view: Split view is more memory intensive

3. Clear cache: Large cached diffs can slow things down

Session History Missing

Symptom: Old sessions not appearing.

Solutions:

1. Check retention settings:

storage:
  session_retention: 30d # Increase retention

2. Sync status: Some sessions may not have synced
3. Storage space: Ensure device has free space

CLI Issues

CLI Won't Start

Symptom: arc0 start fails or exits immediately.

Solutions:

1. Check port availability:

lsof -i :3847

If in use, change the port:

arc0 start --port 3848

2. Check logs:

cat ~/.arc0/arc0.log

3. Permissions: Ensure you have write access to ~/.arc0/

4. Node version: Requires Node 18+ (for npm install)

node --version

High CPU/Memory Usage

Symptom: CLI using excessive resources.

Solutions:

1. Check for runaway sessions: Multiple active sessions can add up

arc0 sessions

2. Reduce logging:

log_level: 'warn' # Reduce from debug/info

3. Limit history:

performance:
  max_history: 500 # Reduce from default 1000

Permission Denied Errors

Symptom: Can't write config or logs.

Solutions:

1. Check directory ownership:

ls -la ~/.arc0

2. Fix permissions:

sudo chown -R $USER ~/.arc0
chmod 755 ~/.arc0

Getting Help

If you can't resolve an issue:

1. Check logs:

arc0 logs --since 1h > debug.log

2. Search issues: GitHub Issues

3. Open issue: Include:

   • Arc0 version (arc0 --version)
   • OS and version
   • Agent being used
   • Steps to reproduce
   • Relevant logs

4. Join Discord: Community Discord

Next Steps