4 MINUTE READ
Troubleshooting
Find the failing layer before changing your workspace.
Start with the doctor
Run the doctor from your terminal. It reports platform support, Git/OpenCode discovery, directory permissions, SQLite health, daemon port availability, workspace paths, and update state. A free daemon port before the first start is expected.
loom doctor
loom logs“loom: command not found”
Restart the terminal after installation. On macOS/Linux, try ~/.loom/bin/loom --version directly. On Windows, try & "$HOME\.loom\bin\loom.exe" --version. If this succeeds, check the PATH entry in your shell profile or User environment variables.
If the installer cannot find a release, check GitHub Releases. Corporate proxies, offline networks, or a channel that has not yet been published can prevent installation.
The UI will not open
Open http://127.0.0.1:4317 manually. Check loom logs for an unavailable OpenCode executable, an occupied port, or an unreadable data directory. Restart with loom restart after fixing the reported problem.
Do not expose the daemon through a public tunnel. Host and Origin checks intentionally reject requests from other sites. In development, configure CORS_ORIGIN to the Vite origin; release builds serve the UI from the daemon's own origin.
A chat or task is stuck
Check which provider and model are selected for the message. For an OpenCode chat or task, verify that OpenCode can answer the same simple prompt directly. For Claude Code, Codex CLI, or Antigravity CLI chat, check that provider's installation, authentication, and model availability. Also resolve any pending permission request in Loom.
Inspect the task's last error and output before retrying. After a daemon interruption, a retained worktree is expected. Do not delete it until you have reviewed or saved its contents.
Share a useful bug report
Include your OS/architecture, loom --version output, the command or UI action, and relevant log lines. Remove tokens, credentials, private paths, prompt content, and source code before publishing logs.