Troubleshooting

Common issues and solutions for 1Code

Installation Issues

Error: Could not find module 'better-sqlite3'

This error occurs when native modules are not properly rebuilt after installation.

Solution:

# Rebuild native modules
bun run postinstall
# or manually
electron-rebuild -f -w better-sqlite3,node-pty

On macOS, make sure you have Xcode Command Line Tools installed:

xcode-select --install

Python setuptools error during install

On Python 3.12+, setuptools is not included by default and is required for native module rebuilds.

Solution:

pip install setuptools
# Then run install again
bun install

We recommend using Python 3.11 for best compatibility with native modules.

Missing Claude or Codex binaries

If the app builds but agents don’t work, you likely skipped downloading the required agent binaries.

Solution:

bun run claude:download
bun run codex:download
# Then rebuild
bun run build

These binaries are required for agent functionality. The app will appear to work but agents will fail without them.

Bun not found or version mismatch

1Code requires Bun as the package manager and build tool.

Solution:

# Install or update Bun
curl -fsSL https://bun.sh/install | bash
# Verify installation
bun --version

Build & Packaging Issues

Electron build fails with code signing error (macOS)

This usually happens when building production packages without proper code signing setup.

Solution for development: Use the dev package command which doesn’t require signing:

bun run package  # Creates unpackaged build in release/ dir

Solution for distribution: Set up code signing with your Apple Developer certificate. See the electron-builder docs for details.

ASAR packaging errors

Native modules (better-sqlite3, node-pty) must be unpacked from ASAR archives.

Verify unpacking configuration in package.json:

"asarUnpack": [
  "node_modules/better-sqlite3/**/*",
  "node_modules/node-pty/**/*",
  "node_modules/@anthropic-ai/claude-agent-sdk/**/*",
  "node_modules/@zed-industries/codex-acp/**/*"
]

If you add new native dependencies, make sure to add them to this list.

dist:manifest script fails

The manifest generation script requires that the build artifacts exist.

Solution:

# Build first, then generate manifests
bun run build
bun run package:mac
bun run dist:manifest

Runtime Issues

Database migration errors on startup

Database auto-migration runs on app startup. If it fails, your database may be corrupted.

Solution:

# Backup and reset database
# Database location:
# macOS: ~/Library/Application Support/1Code/data/agents.db
# Linux: ~/.config/1Code/data/agents.db
# Windows: %APPDATA%/1Code/data/agents.db

# Move old database
mv "~/Library/Application Support/1Code/data/agents.db" "~/agents.db.backup"
# Restart app - it will create a new database

This will reset all your projects and chats. Export important conversations first.

OAuth deep link not working (first install)

On macOS, Launch Services may not immediately recognize protocol handlers on first app launch.

Solution:

1. Close and reopen the app
2. Try clicking “Sign in” again
3. If it still doesn’t work, re-register protocol handlers:

/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -kill -r -domain local -domain system -domain user

Git worktree errors

Worktree operations can fail if the git repository is in an inconsistent state.

Common causes:

• Uncommitted changes in main branch
• Existing worktree with the same name
• Insufficient disk space

Solution:

# Check worktrees
git worktree list
# Remove stale worktrees
git worktree prune
# Check repository status
git status

Agent sessions not resuming

Session IDs are stored in the database. If the database is corrupted or the session expired, it won’t resume.

Solution:

• Start a new chat session
• Check that the project folder still exists
• Verify the worktree hasn’t been manually deleted

Terminal not working or blank

node-pty issues can cause terminal problems.

Solution:

# Rebuild node-pty
electron-rebuild -f -w node-pty

On Linux, make sure you have the required dependencies:

# Ubuntu/Debian
sudo apt-get install -y make python3 build-essential

Development Mode Issues

Hot reload not working

electron-vite handles hot reload for renderer and preload processes.

Solution:

• Make sure you’re using bun run dev not bun run build
• Check the terminal for any compilation errors
• Try restarting the dev server

Changes not appearing in dev mode

If you modify main process code, you need to restart the entire app.

Solution:

• Stop bun run dev (Ctrl+C)
• Run bun run dev again
• Renderer process changes hot reload automatically

DevTools console errors

Open DevTools with Cmd+Option+I (macOS) or Ctrl+Shift+I (Windows/Linux).

Common errors:

• CORS errors: Check that your backend server is running
• Import errors: Verify file paths and check for typos
• State errors: Check Jotai/Zustand state initialization

Debug Mode

For runtime issues that are hard to reproduce, use the structured debug logging system.

1. Start the debug server

   bun packages/debug/src/server.ts &
   
2. Instrument your code

   Add debug logs in renderer or main process:

   fetch('http://localhost:7799/log', {
     method: 'POST',
     headers: {'Content-Type': 'application/json'},
     body: JSON.stringify({
       tag: 'AGENT_START',
       msg: 'Starting agent session',
       data: {sessionId, projectId},
       ts: Date.now()
     })
   }).catch(() => {});
   
3. Reproduce the issue

   Use the app and trigger the problematic behavior.

4. Read logs

   cat .debug/logs.ndjson | jq
   

   Each line is a JSON object with tag, msg, data, and ts fields.

See packages/debug/INSTRUCTIONS.md for the full debug protocol.

Getting Help

If you’re still stuck after trying these solutions:

Join Discord

Get real-time help from the community and core team

GitHub Issues

Report bugs or request features

GitHub Discussions

Ask questions and share solutions

Support

Learn about other support options