Skip to content

Troubleshooting Guide

This guide covers common issues and solutions for AI Code UI.

Quick Diagnostics

Check System Status

cloudcli status

This displays: - Current version - Database location and status - Configuration values - Claude projects folder status

Check Server Logs

Backend logs appear in the terminal running npm run dev or npm run server.

Check Browser Console

Open browser DevTools (F12) → Console tab for frontend errors.

Check WebSocket Traffic

Browser DevTools → Network tab → WS filter

Connection Issues

Server Won't Start

Symptom: Server fails to start or immediately exits.

Solutions:

  1. Check port availability: 

    lsof -i :3001
# If occupied, use different port:
cloudcli --port 8080

  2. Check Node.js version: 

    node --version  # Must be 20.x or later

  3. Reinstall dependencies: 

    rm -rf node_modules package-lock.json
npm install

  4. Check for syntax errors: 

    npm run build  # Will show compilation errors

WebSocket Connection Failed

Symptom: Chat doesn't work, "Connecting..." status persists.

Solutions:

  1. Verify server is running: 

    curl http://localhost:3001/api/health

  2. Check WebSocket endpoint:

  3. Development: ws://localhost:3001/ws

  4. Behind proxy: Ensure WebSocket upgrade is configured

  5. Check browser extensions:

  6. Disable ad blockers temporarily

  7. VPN/proxy extensions may block WebSocket

  8. Check CORS settings:

  9. Server allows all origins by default
  10. Custom deployments may need CORS configuration

Cannot Connect to AI Provider

Symptom: Messages send but no response from AI.

Solutions:

  1. Check API credentials:
  2. Claude: Verify AWS Bedrock credentials or API key
  3. Cursor: Ensure Cursor CLI is authenticated

  4. Codex: Check OpenAI API key configuration

  5. Check environment variables: 

    # For AWS Bedrock
echo $AWS_ACCESS_KEY_ID
echo $AWS_SECRET_ACCESS_KEY
echo $AWS_REGION

  6. Test Claude CLI directly: 

    claude --version
echo "test" | claude

Authentication Issues

Login Fails

Symptom: Cannot log in with correct credentials.

Solutions:

  1. Check database exists: 

    cloudcli status  # Shows database location and status

  2. Reset password (if needed): 

    sqlite3 server/database/auth.db
> DELETE FROM users WHERE username = 'your_username';
> .exit
    Then re-register through the UI.

  3. Check for platform mode:

  4. If VITE_IS_PLATFORM=true, authentication is bypassed
  5. First user in database is used automatically

JWT Token Expired

Symptom: Logged in but API calls fail with 401.

Solutions:

  1. Clear localStorage: 

    // In browser console
localStorage.clear();

  2. Log out and log in again

  3. Note: Current implementation has no token expiration. This issue typically indicates token corruption.

Session Not Persisting

Symptom: Must log in again after page refresh.

Solutions:

  1. Check localStorage is enabled:
  2. Private/incognito mode may block localStorage

  3. Some browsers block third-party storage

  4. Check for browser storage quota: 

    // In browser console
navigator.storage.estimate().then(console.log)

Project Discovery Issues

Projects Not Appearing

Symptom: Sidebar shows no projects or missing projects.

Solutions:

  1. Check Claude projects folder: 

    ls -la ~/.claude/projects/

  2. Verify JSONL files exist: 

    find ~/.claude/projects -name "*.jsonl"

  3. Check file permissions: 

    chmod -R 755 ~/.claude/projects/

  4. Manually add project:

  5. Click "+" in sidebar
  6. Enter project path
  7. Project is added to ~/.claude/projects/project-config.json

Cursor Projects Missing

Symptom: Only Claude projects appear, not Cursor.

Explanation: Cursor uses MD5 hashes of project paths for storage. Discovery requires knowing the path first (cannot reverse-lookup).

Solutions:

  1. Manually add the project path
  2. Open project in Cursor first, then it may be discovered

Sessions Not Loading

Symptom: Project shows but no chat history.

Solutions:

  1. Check session files: 

    # Claude sessions
ls ~/.claude/projects/*/session-*.jsonl

# Cursor sessions
ls ~/.cursor/chats/*/sessions/*/store.db

  2. Verify file is valid JSONL: 

    head -1 ~/.claude/projects/project-name/session-id.jsonl | jq .

  3. Check for file corruption:

  4. Large files may have truncation issues
  5. Invalid JSON lines cause parsing failures

Chat Issues

Messages Not Sending

Symptom: Send button doesn't work or message disappears.

Solutions:

  1. Check WebSocket status: Look for green connection indicator
  2. Check browser console for errors
  3. Verify provider is selected in settings

Tool Approval Stuck

Symptom: Tool approval dialog appears but doesn't respond.

Solutions:

  1. Check for timeout:
  2. Approvals timeout after 55 seconds

  3. SDK cancellation clears pending approvals

  4. Refresh the page:

  5. Pending approvals are cleared on reconnect

  6. May need to resend the message

  7. Check server logs for approval flow errors

Responses Cut Off

Symptom: AI response stops mid-sentence.

Solutions:

  1. Check context window:
  2. Default: 160,000 tokens

  3. Set CONTEXT_WINDOW in .env if needed

  4. Check for abort signals:

  5. User may have accidentally aborted

  6. Network interruption causes abort

  7. Check token limits in response

File Browser Issues

Files Not Loading

Symptom: File tree empty or files won't open.

Solutions:

  1. Check project path exists: 

    ls -la /path/to/project

  2. Check file permissions:

  3. Server runs as current user

  4. Files must be readable

  5. Check for symlinks:

  6. Symlinks outside project root are blocked
  7. Security measure prevents path traversal

Editor Won't Save

Symptom: Save button fails or content lost.

Solutions:

  1. Check write permissions: 

    touch /path/to/project/test-file

  2. Check for file locks:

  3. Other editors may have file open

  4. Git operations may lock files

  5. Check disk space

Terminal Issues

Terminal Not Connecting

Symptom: Shell shows "Connecting..." or blank.

Solutions:

  1. Check PTY support:
  2. node-pty requires native compilation

  3. May need to rebuild: npm rebuild

  4. Check shell availability: 

    echo $SHELL
which bash

  5. Check WebSocket endpoint /shell

Terminal Output Garbled

Symptom: Colors or formatting broken.

Solutions:

  1. Check terminal type:
  2. xterm.js expects xterm-256color

  3. Some shells need TERM configured

  4. Resize terminal:

  5. Drag terminal divider
  6. Triggers resize event

Git Panel Issues

Git Operations Failing

Symptom: Stage, commit, or other git commands fail.

Solutions:

  1. Check git is initialized: 

    git status  # In project directory

  2. Check git configuration: 

    git config user.name
git config user.email

  3. Configure in Settings:

  4. Go to Settings → Git
  5. Set name and email

Branch Operations Fail

Symptom: Cannot switch branches or create new ones.

Solutions:

  1. Check for uncommitted changes
  2. Check for merge conflicts
  3. Verify branch name is valid

Database Issues

Database Locked

Symptom: "Database is locked" errors.

Solutions:

  1. Stop other processes: 

    fuser server/database/auth.db

  2. Check for zombie processes: 

    ps aux | grep node

  3. Delete lock file if exists: 

    rm server/database/auth.db-journal

Database Corruption

Symptom: Queries fail or return unexpected results.

Solutions:

  1. Check database integrity: 

    sqlite3 server/database/auth.db "PRAGMA integrity_check;"

  2. Export and reimport: 

    sqlite3 server/database/auth.db ".dump" > backup.sql
sqlite3 new-auth.db < backup.sql
mv new-auth.db server/database/auth.db

  3. Start fresh: 

    rm server/database/auth.db
# Database recreated on next start

Performance Issues

Slow Page Load

Solutions:

  1. Check build is production: 

    npm run build
npm run server  # Serves optimized build

  2. Check for large session files

  3. Clear browser cache

High Memory Usage

Solutions:

  1. Check for memory leaks in DevTools
  2. Limit chat history display
  3. Close unused terminal sessions

Slow File Tree

Solutions:

  1. Large directories take time to load
  2. Add paths to .gitignore style exclusions
  3. Check for node_modules in project

Getting Help

If issues persist:

  1. Check server logs for detailed error messages
  2. Check browser console for frontend errors
  3. Report issues at GitHub Issues

Include: - Node.js version - Operating system - Error messages - Steps to reproduce

See Also