Skip to main content

​
Common Issues

​
Installation Issues

​
Bun not found

Superset requires Bun v1.0+ as the package manager. 
# Install Bun (macOS/Linux)
curl -fsSL https://bun.sh/install | bash

# Verify installation
bun --version

​
Dependencies fail to install

If bun install fails: 
# Clean and reinstall
bun run clean
bun run clean:workspaces
rm -rf node_modules
bun install

​
Environment variables missing

If you see environment validation errors: Option 1: Configure all required variables 
cp .env.example .env
# Edit .env and fill in the values
Option 2: Skip validation for local testing 
cp .env.example .env
echo 'SKIP_ENV_VALIDATION=1' >> .env

​
macOS-Specific Issues

​
App won’t open (“damaged” warning)

If macOS blocks the app with a security warning: 
# Remove the quarantine attribute
xattr -cr /Applications/Superset.app
Alternatively, go to System Settings > Privacy & Security and click “Open Anyway”.

​
Caddy not found

Superset uses Caddy as a reverse proxy for Electric SQL streams: 
# Install Caddy
brew install caddy

# Copy example config
cp Caddyfile.example Caddyfile

​
GitHub CLI not installed

Some features require the GitHub CLI: 
# Install gh
brew install gh

# Authenticate
gh auth login

​
Git Worktree Issues

​
Worktree creation fails

If workspace creation fails with git worktree errors: 
# List existing worktrees
git worktree list

# Remove stale worktrees
git worktree prune

# Remove specific worktree
git worktree remove <path>

​
Worktree branch conflicts

If a branch already exists: 
# Delete the branch
git branch -D <branch-name>

# Or choose a different workspace name

​
“Worktree already exists” error

This happens if a previous workspace wasn’t cleaned up properly: 
# List all worktrees
git worktree list

# Remove the problematic worktree
git worktree remove --force <path>

# Clean up references
git worktree prune

​
Agent Connection Issues

​
Agent not responding

  1. Check if the agent process is running in the terminal
  2. Look for error messages in the terminal output
  3. Try restarting the workspace
  4. Verify the agent CLI is installed and in PATH

​
Agent commands not found

Ensure the agent’s CLI tool is installed: 
# Example: Installing OpenCode
npm install -g opencode

# Example: Installing Cursor CLI
cursor --install-cli

​
Permission denied errors

Some agents may need execute permissions: 
chmod +x /path/to/agent/binary

​
Terminal Issues

​
Terminal not displaying correctly

  1. Try clearing the terminal: ⌘K
  2. Close and reopen the terminal tab: ⌘W then ⌘T
  3. Restart the workspace

​
Copy/paste not working

Use the standard macOS shortcuts:
  • Copy: ⌘C
  • Paste: ⌘V
If still not working, try clicking in the terminal to ensure it has focus.

​
Terminal font issues

Configure terminal appearance in Settings > Terminal.

​
Performance Issues

​
App running slowly

  1. Close unused workspaces: Each workspace runs in its own git worktree and consumes resources
  2. Limit concurrent agents: Running 10+ agents simultaneously requires significant CPU/memory
  3. Check Activity Monitor: Look for high CPU usage from agent processes
  4. Clear terminal scrollback: Use ⌘K to clear terminal history

​
High memory usage

  1. Close workspaces you’re not actively using
  2. Restart long-running agent processes
  3. Check for memory leaks in agent processes

​
Build failures

If bun run build fails: 
# Clean build artifacts
bun run clean:workspaces

# Run type checking
bun run typecheck

# Run linting
bun run lint

# Try building again
bun run build

​
Database Issues

​
Database connection errors

If you see database connection errors during development:
  1. Verify your .env file has the correct database credentials
  2. Check that you’re not trying to connect to production (unless explicitly intended)
  3. Ensure your local database is running

​
Migration errors

Never manually edit files in packages/db/drizzle/. If you need to create a migration:
  1. Modify schema files in packages/db/src/schema/
  2. Run bunx drizzle-kit generate --name="migration_name"

​
Getting Help

​
Reporting Bugs

If you encounter a bug:
  1. Check existing issues: Search GitHub Issues to see if it’s already reported
  2. Create a new issue: If not found, open a new issue with:
    • Clear description of the problem
    • Steps to reproduce
    • Expected vs actual behavior
    • System information (macOS version, Bun version, etc.)
    • Relevant error messages or logs

​
Community Support

Get help from the community:

​
Debug Logs

When reporting issues, include:
  1. Terminal output from the failing command
  2. Console logs from Developer Tools (if applicable)
  3. Contents of error messages
  4. Your environment setup (OS version, Bun version, Git version)

​
Before Asking for Help

  1. Update to the latest version
  2. Try the troubleshooting steps above
  3. Search existing issues and discussions
  4. Provide clear reproduction steps

​
Still Having Issues?

If none of the above solutions work, please reach out on Discord or open an issue with detailed information about your problem.

Build docs developers (and LLMs) love

Get started for freeTalk to us