Skip to main content
This guide covers frequent issues encountered when developing or using Emdash, along with practical solutions.

​
Native module issues

Emdash uses three native Node.js modules that must be compiled for Electron: sqlite3, node-pty, and keytar.
Symptoms: App crashes immediately with errors mentioning sqlite3, node-pty, or keytarCommon error messages:
Error: The module was compiled against a different Node.js version
Error: Cannot find module 'sqlite3'
Error: dyld: lazy symbol binding failed
Solutions:
1

Rebuild native modules

Run the rebuild command:
pnpm run rebuild
This recompiles native modules for your current Electron version.
2

Clean install if rebuild fails

If rebuild doesn’t fix it, do a full clean install:
pnpm run reset
This removes node_modules and reinstalls everything from scratch.
3

Verify Node version

Emdash requires Node.js 22.x. Check your version:
node --version
If incorrect, install the right version:
nvm install 22.20.0
nvm use 22.20.0
Or use the .nvmrc file:
nvm use
4

Check platform-specific dependencies

Linux: Install build tools and required libraries
# Ubuntu/Debian
sudo apt install build-essential python3 libsecret-1-dev

# Fedora
sudo dnf install @development-tools python3 libsecret-devel

# Arch
sudo pacman -S base-devel python libsecret
macOS: Install Xcode Command Line Tools
xcode-select --install
Windows: Install Visual Studio Build Tools
npm install --global windows-build-tools
Symptoms: Database operations fail, errors like “Cannot find module ‘node_sqlite3.node’”Solutions:
  1. Rebuild sqlite3 specifically: 
    pnpm rebuild sqlite3
  2. If that fails, use the fallback database driver: 
    export EMDASH_DISABLE_NATIVE_DB=1
pnpm run dev
  3. Check the database file isn’t corrupted (see Database corruption)
Symptoms: Terminal doesn’t work, PTY spawn failsCommon error:
Error: Cannot find module 'node-pty'
Solutions:
  1. Ensure you have Windows Build Tools: 
    npm install --global windows-build-tools
  2. Rebuild node-pty: 
    pnpm rebuild node-pty
  3. If using WSL, build inside WSL (not Windows)
Symptoms: Credential storage fails, SSH passwords not savedCommon error:
Error: The module 'keytar' was compiled against a different Node.js version
Solutions:
  1. Install libsecret: 
    # Ubuntu/Debian
sudo apt install libsecret-1-dev gnome-keyring

# Fedora
sudo dnf install libsecret-devel gnome-keyring

# Arch
sudo pacman -S libsecret gnome-keyring
  2. Rebuild keytar: 
    pnpm rebuild keytar
  3. Start gnome-keyring if not running: 
    gnome-keyring-daemon --start --components=secrets

​
Agent and PATH issues

Symptoms: Task creation fails with “Agent not found” or “command not found: claude”Why this happens:When Emdash is launched from the GUI (Finder, Dock, application launcher), it may not inherit your shell’s PATH configuration.Solutions:
1

Verify agent is installed

Test in a terminal:
which claude  # or codex, amp, etc.
If this returns nothing, install the agent first.
2

Launch Emdash from terminal

Launching from a terminal inherits your shell’s PATH:
pnpm run dev
If this works, the issue is PATH configuration.
3

Add agent to system PATH

macOS/Linux: Add to shell profile (~/.zshrc, ~/.bashrc, etc.)
export PATH="$HOME/.local/bin:$PATH"  # or wherever the agent is installed
Reload:
source ~/.zshrc
Windows: Add to System Environment Variables via Settings
4

Check Emdash PATH setup

Emdash tries to fix PATH on startup in src/main/main.ts. If your agent still isn’t found, you may need to add the installation directory to this logic.Common locations Emdash checks:
  • /usr/local/bin
  • /opt/homebrew/bin
  • ~/.local/bin
  • ~/bin
  • ~/.nvm/versions/node/*/bin
  • ~/.npm-global/bin
Symptoms: Agent is in PATH but doesn’t appear in provider dropdownSolutions:
  1. Check the provider definition in src/shared/providers/registry.ts:
    • Verify commands array matches the actual binary name
    • Ensure detectable is not set to false
    • Check versionArgs succeeds (e.g., claude --version)
  2. Restart Emdash — detection runs on startup
  3. Check the console for detection errors (Cmd+Option+I / Ctrl+Shift+I)
Symptoms: Agent starts but can’t access API keys (e.g., ANTHROPIC_API_KEY not found)Why this happens:PTYs use a minimal environment that doesn’t inherit process.env. Only keys in AGENT_ENV_VARS are passed through.Solutions:
  1. Add the key to AGENT_ENV_VARS in src/main/services/ptyManager.ts: 
    const AGENT_ENV_VARS = [
  'ANTHROPIC_API_KEY',
  'OPENAI_API_KEY',
  // Add your key here
  'MY_AGENT_API_KEY',
];
  2. Set the key in your shell environment: 
    export MY_AGENT_API_KEY="your-key-here"
  3. Restart Emdash to pick up the new environment

​
Git and worktree issues

Symptoms: Task creation fails with “Failed to create worktree” or “worktree already exists”Common errors:
fatal: 'worktrees/task-name-abc' already exists
fatal: invalid reference: emdash/task-name-abc
Solutions:
1

Clean up orphaned worktrees

cd /path/to/your/repo
git worktree prune
2

Manually remove stuck worktree

rm -rf ../worktrees/task-name-abc
git worktree prune
git branch -D emdash/task-name-abc
3

Check .git/worktrees for corruption

ls -la .git/worktrees/
If you see broken symlinks or empty directories, remove them:
rm -rf .git/worktrees/task-name-abc
Symptoms: “reference is not a tree” or “branch already exists”Solutions:
  1. Delete the conflicting branch: 
    git branch -D emdash/task-name-abc
  2. Let Emdash recreate it automatically
  3. If the branch exists in remote, fetch and track it: 
    git fetch origin emdash/task-name-abc
git checkout emdash/task-name-abc
Symptoms: .env, .envrc, or other gitignored files missing in worktreeSolutions:
  1. Check .emdash.json in project root: 
    {
  "preservePatterns": [
    ".env",
    ".envrc",
    ".claude/**"
  ]
}
  2. Ensure the files exist in the main repo (not just in another worktree)
  3. Re-create the task to trigger a fresh worktree with preserved files

​
Database issues

Symptoms: App crashes on startup, errors like “database disk image is malformed”Solutions:
1

Locate the database file

  • macOS: ~/Library/Application Support/emdash/emdash.db
  • Linux: ~/.config/emdash/emdash.db
  • Windows: %APPDATA%\emdash\emdash.db
2

Backup the corrupt database

cp ~/Library/Application\ Support/emdash/emdash.db ~/emdash-backup.db
3

Attempt recovery with sqlite3

sqlite3 ~/Library/Application\ Support/emdash/emdash.db ".recover" | sqlite3 emdash-recovered.db
If successful, replace the original:
mv emdash-recovered.db ~/Library/Application\ Support/emdash/emdash.db
4

Last resort: delete and recreate

This deletes all tasks, conversations, and settings.
rm ~/Library/Application\ Support/emdash/emdash.db
Emdash will create a fresh database on next launch.
Symptoms: “Migration failed” or “column not found” after updateSolutions:
  1. Check the current schema version: 
    sqlite3 ~/Library/Application\ Support/emdash/emdash.db "SELECT * FROM __drizzle_migrations;"
  2. If migrations are stuck, manually run them: 
    pnpm exec drizzle-kit migrate
  3. If migrations fail, restore from backup or delete the database
Symptoms: “database is locked” or “unable to open database file”Solutions:
  1. Ensure only one instance of Emdash is running
  2. Check for zombie processes: 
    ps aux | grep emdash
kill -9 <pid>
  3. Remove stale lock files: 
    rm ~/Library/Application\ Support/emdash/emdash.db-wal
rm ~/Library/Application\ Support/emdash/emdash.db-shm

​
PTY and terminal issues

Symptoms: Terminal opens and closes instantly, no outputSolutions:
  1. Check agent CLI is correct in provider definition
  2. Test the command manually: 
    claude --version  # or your agent
  3. Check for missing dependencies (Python, Node.js, etc.)
  4. Look for errors in Electron console (Cmd+Option+I / Ctrl+Shift+I)
Symptoms: Terminal shows escape codes or no outputSolutions:
  1. Try resizing the terminal pane
  2. Restart the PTY (close and reopen the task)
  3. Check PTY dimensions are correct: 
    const MIN_PTY_COLS = 2;
const MIN_PTY_ROWS = 1;
  4. Disable terminal features like ligatures or complex rendering
Symptoms: Zombie processes or orphaned tmux sessionsSolutions:
  1. Manually kill tmux sessions: 
    tmux kill-session -t emdash-claude-main-<task-id>
  2. Kill orphaned PTYs: 
    ps aux | grep node-pty
kill -9 <pid>
  3. Check ptyManager.ts calls removePty() on exit

​
Development and build issues

Symptoms: pnpm run type-check fails with type errorsSolutions:
  1. Reinstall dependencies: 
    pnpm install
  2. Clear TypeScript cache: 
    rm -rf dist/
pnpm run build
  3. Check you’re on the correct Node version: 
    nvm use
  4. Verify path aliases are correct in tsconfig.json and tsconfig.main.json
Symptoms: Changes don’t appear after saving filesSolutions:
  • Renderer process: Should hot-reload via Vite automatically
  • Main process: Requires full restart (Ctrl+C then pnpm run dev)
  • Native modules: Require pnpm run rebuild
Symptoms: CI fails with “Module not found” or compilation errorsSolutions:
  1. Ensure CI uses correct Node version (22.x)
  2. Check native module binaries aren’t committed: 
    git status
git clean -fdx node_modules/
  3. Verify all required environment variables are set in CI
  4. Check platform-specific dependencies are installed (see native module section)
Symptoms: pnpm exec vitest run failsSolutions:
  1. Ensure test environment is correct in vite.config.ts: 
    test: {
  environment: 'node',
}
  2. Check mocks are correctly set up (tests use vi.mock())
  3. Verify temp directories are writable: 
    ls -la /tmp  # or os.tmpdir() output
  4. Run a specific test to isolate the issue: 
    pnpm exec vitest run src/test/main/WorktreeService.test.ts

​
Platform-specific issues

Symptoms: “App is damaged and can’t be opened” or Gatekeeper blockingSolutions:
  1. Remove quarantine attribute: 
    xattr -cr /Applications/Emdash.app
  2. Allow app in System Preferences → Security & Privacy
  3. For development builds, disable Gatekeeper temporarily: 
    sudo spctl --master-disable
    Re-enable after: 
    sudo spctl --master-enable
Symptoms: App doesn’t launch or crashes on WaylandSolutions:
  1. Force X11 mode: 
    export ELECTRON_OZONE_PLATFORM_HINT=x11
pnpm run dev
  2. Or use Wayland explicitly: 
    export ELECTRON_OZONE_PLATFORM_HINT=wayland
pnpm run dev
  3. Ensure required env vars are set: 
    echo $WAYLAND_DISPLAY
echo $XDG_RUNTIME_DIR
Symptoms: pnpm commands fail with “execution policy” errorSolutions:
  1. Allow scripts for current user: 
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  2. Or run in Administrator mode: 
    Set-ExecutionPolicy RemoteSigned

​
Debugging tips

1

Enable Electron DevTools

Press Cmd+Option+I (macOS) or Ctrl+Shift+I (Windows/Linux) to open DevTools.Check Console tab for errors.
2

Check main process logs

Main process logs go to terminal stdout when running pnpm run dev.Look for errors from log.error() calls.
3

Inspect database directly

sqlite3 ~/Library/Application\ Support/emdash/emdash.db

.tables
SELECT * FROM tasks LIMIT 5;
.exit
4

Use Drizzle Studio for database inspection

pnpm exec drizzle-kit studio
Opens a web UI at http://localhost:3000.
5

Test IPC handlers directly

In DevTools console:
await window.electronAPI.checkGitHubConnection()
await window.electronAPI.getTasks({ projectId: 'abc' })

​
Getting help

If you’re still stuck:
  1. Check GitHub issues: https://github.com/emdash-ai/emdash/issues
  2. Search AGENTS.md: The internal dev guide has detailed architecture notes
  3. File a bug: Include logs, error messages, OS/Node versions, and steps to reproduce
When filing issues, attach relevant logs and always include:
  • Operating system and version
  • Node.js version (node --version)
  • Emdash version or commit hash
  • Full error message and stack trace

​
Preventive maintenance

1

Run quality checks before committing

pnpm run format
pnpm run lint
pnpm run type-check
pnpm exec vitest run
2

Rebuild native modules after updates

After pulling changes that update node-pty, sqlite3, or keytar:
pnpm run rebuild
3

Keep database backed up

cp ~/Library/Application\ Support/emdash/emdash.db ~/backups/emdash-$(date +%Y%m%d).db
4

Monitor worktree disk usage

Worktrees can accumulate:
du -sh ../worktrees/*
Clean up old ones:
git worktree prune

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us