Troubleshooting

Troubleshooting & FAQ

Common issues and how to resolve them.

Installation Issues

"lantern: command not found"

The binary is installed but your shell hasn't loaded the updated $PATH.

Fix:

source ~/.zshrc
lantern --version

"Rust not found" or "cargo not found"

Rust is not installed or not in your $PATH.

Fix:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
source ~/.zshrc

"Temporal CLI not found"

Fix:

brew install temporal-cli
source ~/.zshrc

"Build failed" or compile errors

Make sure you have Rust 1.70+:

rustc --version

If you're below 1.70, update:

rustup update

Then try building again:

cargo build --release

Runtime Issues

"iTerm2 window didn't open"

Lantern requires iTerm2 (not Terminal.app).

Fix:

Install iTerm2 from https://iterm2.com/ or:

brew install iterm2

"lantern up" hangs or fails

Services might already be running or ports are in use.

Fix:

lantern down
sleep 2
lantern up
lantern doctor

"Temporal server won't start"

Port 8243 or 8244 might be in use.

Fix:

lsof -i :8243
lsof -i :8244

Kill any process using these ports, then:

lantern restart

Agent pane shows "Connection refused"

The MCP server isn't running or the agent CLI isn't configured.

Fix:

lantern doctor        # Check all services
lantern up            # Start services if needed
lantern startwork myproject  # Try again

Squad Issues

"worktree root already exists"

A squad with that session ID is already active or wasn't cleaned up properly.

Fix:

lantern status                # Find the session ID
lantern stopwork myproject-1  # Stop the squad
lantern startwork myproject   # Try again with a different slot number

Agent pane frozen or unresponsive

The agent might be stuck or crashed.

Fix:

lantern recover myproject-1-ai

"Can't find project repository"

Make sure you're in the correct directory:

pwd
git status
lantern startwork

If the repo name is different, specify it:

lantern startwork my-repo-name 1

Development Issues

Tests are failing

Make sure all dependencies are up to date:

cargo test

If tests fail with SQLite errors, you may need to set up the offline cache:

SQLX_OFFLINE=true cargo test

Code formatting issues

Format your code before committing:

cargo fmt

Check that it passes the format check:

cargo fmt --check

Linter warnings

Run clippy to see all warnings:

cargo clippy

Fix any critical warnings before pushing.

Logs & Debugging

View Relay logs

lantern logs relay

View Temporal logs

lantern logs temporal

Enable debug logging

RUST_LOG=debug lantern up
RUST_LOG=debug lantern startwork myproject

FAQ

Can I use Lantern on Linux or Windows?

Not yet. Lantern is macOS-only (iTerm2 dependency). Linux and Windows support are planned for a future release.

Do I need a Temporal server?

No. Temporal is optional and used for workflow logging. Lantern works fine without it.

Can I run multiple squads simultaneously?

Yes! Each squad is independent. Use different slot numbers:

lantern startwork project-a 1
lantern startwork project-a 2
lantern startwork project-b 1

lantern status  # shows all active squads

How do I stop a squad but keep the git worktrees?

lantern stopwork myproject-1 --preserve-worktrees

This closes the terminal window but leaves the branches and worktrees in place for manual cleanup.

Can I use a different agent CLI?

Yes! Lantern supports:

• claude (default)
• codex (OpenAI)
• kimi (Kimi/MoonshotAI)
• gemini (Google)
• agy (AGI Lab)
• goose (solo mode)

lantern startwork myproject 2 --agent codex

Where does Lantern store data?

All data is stored locally at ~/.lantern/:

• State: ~/.lantern/data/relay/lantern.db (SQLite)
• Temporal data: ~/.lantern/data/temporal/ (optional)
• Logs: ~/.lantern/logs/
• Config: ~/.lantern/config/ (rarely used)

Is Lantern secure?

Lantern is designed for local development only. No cloud connectivity, no credentials, no secrets. See Security for details.

Still stuck?

• Check the Command Reference
• File an issue on GitHub
• Review Installation & Setup for prerequisite setup