Symptoms and fixes for installing, signing in, connecting stores and running Loom in a coding agent.
loom command is not found#Re-run the installer for your operating system (see Install the CLI) and open a new terminal so the changed PATH is picked up. On Linux and macOS the command lives at ~/.local/bin/loom; on Windows at %USERPROFILE%\.loom\bin\loom.cmd.
Related errors:
| Message | Meaning | Fix |
|---|---|---|
loom: hosted CLI runtime is not installed; rerun the official Loom install skill (exit code 1) | The launcher cannot find the CLI runtime under ~/.loom/cli. | Re-run the installer. |
loom: runtime environment is missing; rerun the official Loom install skill (exit code 1) | The launcher cannot find ~/.loom/venv. | Re-run the installer. |
loom setup: unknown argument '--help' (exit 2) | loom setup, loom login and the other built-in commands do not take --help in v0.674, and updating to v0.674 does not change that. loom --help lists only the tool commands, and loom <tool> --help and loom fleet --help do work. A later release lists the built-in commands in loom --help and answers loom setup --help. | Use the CLI reference for the built-in commands and their options. |
loom_mcp.py needs mcp>=1.26,<2 (mcp 2.x is not supported): install it with pip install 'mcp>=1.26,<2'`` | The Python mcp package in that environment is version 2.x, which renamed what Loom imports (a plain pip install mcp pulls it). Printed instead of an import traceback when loom_mcp.py starts in such an environment (for example a manual Hermes setup), v0.674 or later. | Install the pinned version in that environment. |
loom setup finds no supported harness#Install Claude Code, Codex or OpenCode, confirm its executable runs in a new terminal, then re-run loom setup. With no harness detected, loom setup prints loom setup: no supported harness found on this machine (looked for: codex, claude, opencode). Install one and re-run. and exits with status 2 before asking for anything; nothing is written. To sign in without a harness, use loom login.
Read the per-harness result table. Successful integrations stay installed. The failed row shows its error and whether a restart is needed. Fix that harness and re-run loom setup; keep every detected harness selected unless you deliberately want to skip one. A partial setup exits with status 3.
| Row | Meaning | Fix |
|---|---|---|
claude FAILED -- claude: the existing Loom marketplace comes from <source> but this setup is for <server> (...), so nothing was changed. To switch deliberately, run ... | Claude Code or Codex already has a loom plugin source from a different server than the one this setup used, and setup will not replace it silently. Nothing was changed for that harness. A conflicting marketplace may instead surface only as install step plugin marketplace failed (exit status 1). | If the other server was the mistake, re-run loom setup with the right --base. To switch on purpose, run the removal commands the row prints (or claude plugin uninstall loom@loom and claude plugin marketplace remove loom), then re-run loom setup (with --base <server> for a private server). |
claude FAILED -- claude: install step plugin marketplace failed (exit status 1) on a private server with a self-signed certificate | Claude Code and Codex fetch the plugins from <server>/loom-plugins.git with git, which rejects a certificate the operating system does not trust (git ls-remote https://<server>/loom-plugins.git says server certificate verification failed). Your stores were still set up. | Add the server's certificate to the operating system trust store (or have the administrator install a certificate from a public or company CA), then re-run loom setup --base https://<server>. See Trust the server's certificate. Verified on Linux with Claude Code. |
claude skipped (plugins need an https server), after Plugins need an https server: ... | The server is an http:// address. Your stores were set up, but the Claude Code and Codex plugins are installed only from an https server. | Use an https server address for plugins (see Set up and log in). |
If loom setup stops with stores.toml section '<name>' has an invalid web_origin, fix that line in stores.toml or pass --base; see stores.toml reference.
Start loom setup (or loom login) again and use only the newest email.
| Symptom | Cause | Fix |
|---|---|---|
| No email arrives | The service replies the same way whether or not the address can receive mail. The first email can take a minute or two. | Check spam; wait a couple of minutes; request a new code. |
too many sign-in code requests for this address; wait a few minutes and run it again (exit code 2) | Too many code requests (5 per address in a short window; requests from one computer may also be limited). The server sent no email. A server older than v0.674 did not say so: the CLI still printed If that address can receive mail, a sign-in code is on its way., no email arrived, and a code from an earlier email failed with that code or link is not valid. | Wait about five minutes, then request once and use the newest email. |
loom login: that code or link is not valid (exit code 2) | Codes last 10 minutes, are single-use, and allow 5 attempts. The CLI exits instead of prompting again. | Re-run loom login, request a new code and enter the newest one. |
provisioning is taking longer than expected; run login again with the same email to check status -- it is safe to retry (exit code 2) | The CLI waits up to 120 seconds for provisioning, including all three starter stores, and retries a status check that times out. Provisioning continues on the server. | Run loom login again with the same email and the newest code. |
provisioning failed; run login again to retry -- it is safe (exit code 2) | The server reported a failure. From v0.674 this also covers a provisioning run that was killed part-way (it used to read as "still provisioning" forever), and an account that ended up with no stores is provisioned again. | Run loom login again with the same email and the newest code. |
Sign-in finished but coding is missing from loom list_stores | The account's coding store was dropped. From v0.674 sign-in writes the stores the account still has instead of polling until it times out. | loom login writes the stores you still have but no top-level default, so loom first fails with `must set top-level default = "<store>" . Add default = "kanban" (or another section) to ~/.loom/stores.toml, then use those stores or create a new one with loom create_store` (see Manage stores). |
The read operation timed out (a Python traceback) | One of the earlier requests (sending the code, checking it, or enrolling) timed out after about 20 seconds; only the wait for provisioning is retried automatically (from v0.672 the waits inside create_store, drop_store and unlock_store also survive a timed-out check). | Run loom login again with the same email and the newest code. |
Warning: store <handle> was not configured locally: its section name [<name>] is already used by another of your stores ... (stderr, exit code 0) | Your account has two stores with the same section name. The oldest one is kept. | Use the kept store. The skipped store has no local section; it was most likely created by running loom create_store with a name that already exists as a section, so choose a different name for new stores. |
loom login: consent was not given; nothing was signed up or provisioned (exit code 1) | You did not type I agree. Consent is asked before any code is emailed, so declining sends no email. | Re-run and review the displayed Terms and Privacy versions. |
loom login: no input available (stdin is closed or not a terminal); run it from an interactive terminal (exit code 2) | End-of-input (Ctrl-D, a closed stdin or a non-interactive run) at the email, consent or code prompt. Earlier releases printed a Python EOFError traceback. Nothing was signed up. | Run it from an interactive terminal and answer the prompts. |
loom login: interrupted; anything already sent to the server may have completed. Re-running loom login is safe. (exit code 130) | You pressed Ctrl-C. stores.toml is written only once the sign-in has finished. Earlier releases printed a traceback. | Re-run the command. |
Type the code only at the hidden prompt. Never put it on the command line.
| Symptom (Private) | Cause | Fix |
|---|---|---|
loom login: could not reach the Loom server: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate (_ssl.c:1000) (exit code 2) | The server uses a self-signed or private-CA certificate that this computer does not trust. | Trust the certificate in the operating system trust store. See Trust the server's certificate. |
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Cancelled (for example consent declined) |
| 2 | Usage error, invalid --base, or a failure before the server was changed |
| 130 | Interrupted with Ctrl-C (setup and login) |
| 3 | Partial result: a lifecycle operation did not settle (status is not ok), a store command such as create_store failed, or loom setup could not finish one harness |
Automation should read the exit code before the JSON output.
create_store did not finish#When the server may already have created the store (for example a "status": "pending" timeout), the detail ends with Store '<name>' may already exist on the server; run loom login ... to register it locally instead of retrying the create. If stores.toml already has the section the name would give (for example notes when you create Notes), the create is refused before any request with stores.toml already has a [notes] section; refusing to replace it ... Nothing was created on the server. (v0.674 or later; earlier releases made a second store notes_2 on the server first, which used up a slot): choose another name or remove that section. Other errors, such as no store named '<x>' in <path>. Configured: ... (bad auth_store) or stores.toml already binds [<name>] to a different store; refusing to replace it, carry no hint. When the hint is present, follow it: run loom login (with --base <origin> on a private server), then loom list_stores. Retrying the create makes a second store and uses another slot of your limit. create_store sends its request to the server recorded as web_origin on the section it authenticates with (auth_store, default the first section), so no environment variable is needed on a private install. See loom_create_store.
Setup preserves unknown configuration and never rebinds an existing named store to a different store: stores.toml already binds [<name>] to a different store; refusing to replace it. Remove or rename that section first. (exit code 2). If it reports a conflict, choose the disposition it offers. Do not delete stores.toml, replace it with another person's copy, or overwrite the conflicting file.
loom list_stores
loom describe_store --store codingA stores.toml section counts as a store only if it has an endpoint key. A section without one is omitted from list_stores, and naming it gives the following (the ~ is expanded to your home directory):
loom: loom store 'NAME' must set `endpoint` in /home/<you>/.loom/stores.toml; db= stores are no longer supportedA name that is not in the file at all gives:
loom: loom store 'nosuch' not in /home/<you>/.loom/stores.toml. Available stores: coding, noendpointThe Available stores: list also includes sections that have no endpoint (here noendpoint), even though loom list_stores omits them. Both errors exit with code 2. A store that is not the default is loaded automatically the first time you use --store NAME. Each loom command is its own process, so loaded in list_stores only reflects the current default. See stores.toml reference.
loom and the agent disagree about the default store#The agent reads stores.toml when its session starts. After loom setup or loom login, restart the harness session. For a one-session override, have the agent load the store with set_default: true (load_store; from the shell the loom command is a one-shot process, so it has no lasting effect); for a repository, use the [workspace] mapping (see the stores.toml reference).
A hook that never fires produces no error; the session simply has no injected context. Prove it fired instead of checking the file exists:
/hooks to see the registered hooks.If nothing appears, restart the harness, re-run loom setup, and check that ~/.loom/venv/.loom-ready exists. The installer writes it when the runtime is complete; the loom launcher itself does not read it.
| Symptom | Fix |
|---|---|
loom not found after install | Open a new PowerShell window; the installer updates your user PATH. |
| Garbled characters in output | Set PYTHONUTF8=1 for your user. |
Open a GitHub issue with your operating system, harness name and version, loom --version, and the exact redacted error. Report security vulnerabilities privately to info@loomcloud.ai, never in a public issue.