Help
Troubleshooting
Real LoCrew error messages and what to do about them, covering installation, runtime sign-in, providers, MCP servers, messages and mentions, hand-offs and limits, file access, sessions, flows, HTTP steps and stored keys.
Each entry quotes the message you see in LoCrew, explains the cause, and gives the fix. Use the page search (Ctrl+K) to find a message.
Note
Toasts may show a technical prefix such as Error invoking remote method '…' in front of the message quoted here.
#Installation and launch
NODE_MODULE_VERSION error on startup. The SQLite module was built for the wrong runtime. Run npm run rebuild.
Electron starts but no window appears. ELECTRON_RUN_AS_NODE is set in your shell, which makes Electron run as plain Node.js. Unset it and start again.
**A dialog titled LoCrew failed to start.** Startup failed before the window loaded, for example because the database could not be opened or a migration failed. The dialog shows the reason. Back up the data folder before trying fixes; see Local data and privacy.
**The window shows LoCrew could not start.** The interface failed to load. The text below it shows the error.
Unknown IPC channel: … while developing. A stale process. npm run dev reloads the interface but not the main process. Restart npm run dev.
npm run dist refuses to build. It only builds tagged version snapshots with no modified files. Use npm run package for a local, unpacked build. On Windows, signed installers also need code-signing tools.
Your agents and conversations seem to be missing after an upgrade. If you used LoCrew when it was called AgentWorkspace, it keeps using the old data folder. Check Settings → About → Data folder.
#Runtimes and sign-in
Claude Code was not found on PATH. Install it with "npm i -g @anthropic-ai/claude-code", then reopen this window. Install it, run claude once to sign in, then press Check again.
Claude Code … is installed but the auth probe failed: … Run claude in a terminal and complete the login, then Check again.
The Codex CLI could not be located. It normally ships with LoCrew. Run npm install again in the LoCrew folder, or install it with npm i -g @openai/codex.
Codex … is available … but is not signed in. The CLI ships with the app, but the login does not. Run npx codex from the LoCrew folder and sign in.
The sign-in check fails although the CLI works in your terminal. LoCrew runs the CLI with its own environment. If your login depends on a shell profile that desktop apps do not load, start LoCrew from that terminal.
Signed out of Claude Code (or Codex): the login expired or was revoked. Sign in again to continue. Use the banner: Sign in to … opens a terminal with the login command (claude auth login, or codex logout then codex login). Finish in the browser, then press I’ve signed in. If no terminal opens, run the command yourself. If the banner says Still not signed in, the check still fails; try the login again. A plain HTTP 401 from another service never triggers this banner.
**An agent shows Unavailable.** Its runtime could not be found at startup. Install it, or for a model agent check that its provider still exists and a model is selected.
**An agent shows Needs attention.** Its last run failed. Open its settings or the conversation to see the error.
#Providers and models
| Message | Fix |
|---|---|
| … rejected the credentials (HTTP 401/403) | Check the API key and the authentication type in Settings → AI Providers. If you moved your data folder to another computer, re-enter the key. |
| … could not find that endpoint or model (HTTP 404) | Check the base URL and model id. For Azure, use the deployment name. |
| Could not reach … : connection refused (is the server running?) | Start your local model server. |
| … is rate limiting requests (HTTP 429) | Wait, or lower Max agents working at once. |
| Remote endpoints must use https://. | Only localhost may use http:// for providers. |
| … is used by …. Move that agent to another provider first. | Change those agents' provider before removing it. |
| … does not accept tools, so … will answer without them. | Not an error: the model cannot call tools, so it cannot use MCP tools or hand off work. Choose a model with tool support if you need them. |
| … has no provider. Choose one in the agent's settings. | The agent's provider was removed. |
More in AI providers.
#MCP servers
| Message | Fix |
|---|---|
| Launching this server needs your approval. Click Connect to review the command. | Press Connect and approve the command. Servers that connect on startup never prompt. |
| Launch was not approved. | Press Connect again and choose Launch. |
| Timed out while connecting. | Raise Request timeout, or check the command runs in a terminal. |
| The server closed the connection. Last output: … | Read Recent output (stderr) on the server card's Server tab. |
| You are not permitted to use "…", or it is no longer available. (seen by the agent) | Grant the tool in the agent's MCP tools. |
#Messages and mentions
A channel message did nothing. Only agents you @mention are woken. LoCrew posts Nobody was woken. Mention an agent to give it the message: …. Direct messages need no mention.
Unknown mention: No agent in this conversation matches @…. The name matches no member. Add the agent to the channel, or check the spelling. Matching ignores case, spaces, dots, underscores and hyphens.
An agent wrote "@Reviewer" but the reviewer did nothing. Text never wakes an agent. Agents hand off work only with the send_message tool. See Agent hand-offs.
Message not sent. Your text and attachments are restored; the toast says why. A message needs text or an image. means it was empty.
Image errors. A message can carry at most 8 images., … is larger than 10 MB., These images add up to more than 30 MB., … is not a PNG, JPEG, GIF or WebP image.
**An agent is stuck in Queued. It is waiting for a free slot (Max agents working at once) or for another agent to finish writing in the same directory. The Working directories** section of the Details panel shows who holds the lock.
#Hand-offs and limits
Stopped here: … Send a new message to continue. A limit stopped the chain. Send a new message to start a fresh chain, or raise the limit in Settings → Limits. Every reason is listed in Limits.
A hand-off never woke the other agent. Check, in order: the target is a member of the channel; Let agents talk to each other is on in Settings and in the channel's settings; the target's Other agents can hand work to it is on; the target's model accepts tools (for model agents); the target is not an external A2A agent.
The execution timed out. The run hit the shortest of the agent's timeout and Max task duration. Raise them, or split the work. In the Activity panel a timed-out run is listed as Stopped.
The agent reached its turn limit / spend limit for this execution. Raise Max turns per message or Spend ceiling in the agent's Permissions.
#File access and approvals
"…" has read-only access to …. The operator must grant write access before … can run. The agent is Read only. Change its access level if it should write.
You denied this operation. You denied the approval, or closed the dialog, which counts as a denial.
The run was stopped before you answered. / The window was closed before you answered. / The app is closing. A pending approval was refused because the run, the window or the app went away.
Could not start the work session. See the reasons in Work sessions.
A Codex agent on Ask first never shows the approval dialog. LoCrew's dialog is only shown for Claude Code. Codex uses its own approval policy. Use Read only for Codex agents you do not want to write.
#Sessions
An agent forgot what it discussed in another channel. Expected: each agent has a separate session per conversation. See Sessions.
An agent started fresh after you changed its folder. Changing an agent's working directory clears its sessions on purpose.
A run fails every time it resumes. LoCrew keeps the stored session and tries again. Start fresh by duplicating the agent or opening a new channel; see Clearing a session.
#Flows
The Run button is disabled. The flow has unsaved changes (Save your changes before running.) or problems (Fix the problems first.). Open the problem list in the header.
This flow cannot run yet: … The flow has validation errors. See Build a flow.
This flow was saved elsewhere (now version N, you edited version M). Reload it before saving. Another editor saved first. Go back to Flows, reopen it, and reapply your change.
No value for {{…}}: that step did not run or did not produce it. A placeholder refers to a value that does not exist on this path. For {{start.json.prompt}}, start the flow with /run instead of Run, or use {{start.text}}.
The reply did not match the fields this step asks for: … The agent's JSON reply missed a declared field or used the wrong type. Allow more Attempts, make the task clearer, or check the field names.
Not started: this run already started 200 agent steps (limit 200) / this run has spent … (limit …). The run's budget is used up. Raise Max spend per chain or simplify the flow.
A run failed as soon as one parallel branch failed. That is the default for Join branches. Set the join to Continue with the branches that succeeded if partial results are fine.
The run went over its time limit of … and was stopped. Raise Time limit for the whole run on the start step. Time waiting for approval counts.
LoCrew stopped while this run was in progress. The run is Interrupted. Open it in Runs and press Resume.
A scheduled run did not happen. Schedules run only while LoCrew is open; a missed run is skipped unless you chose Run once when LoCrew opens. If the previous run was still going, the new one is skipped. Check that you saved the flow after turning the schedule on.
/run notes. See When /run is refused.
This flow has a run in progress. Cancel it before deleting the flow. Cancel the run in Runs first.
#HTTP steps
| Message | Fix |
|---|---|
| The URL uses unencrypted http://. | Use https://, or turn on Allow unencrypted http://. |
| … is a private address. / … resolves to a private address (…). | Turn on Allow local and private network addresses if you really mean to call a local service. |
| The host must be written out: values from earlier steps may only go in the path or query. | Write the host in the URL; insert values only after it. |
| No response within … s. | Raise Time limit (seconds) (up to 120). |
| The response is larger than … KB. | Raise Largest response (KB) (up to 10,240), or ask the API for less. |
| More than 5 redirects. | Use the final address. |
| HTTP 401 Unauthorized | Check the saved key and the authentication type. |
| The response has no value for … | The kept value's path is wrong, or the API returned a different shape. Send a test request and use Keep. |
| The saved credential for this step no longer exists. | Choose or add a key. |
#Keys and data
Secure credential storage is not available on this system, so the key was not saved. On Linux, install and unlock GNOME Keyring or KWallet, then try again. LoCrew never stores keys in plain text.
Keys stopped working after moving to another computer. Encrypted keys can only be read by the account that saved them. Enter them again.
#Still stuck?
Note your OS, Node.js version, LoCrew version (Settings → About → Copy versions), the steps to reproduce and the exact message, with any keys removed, and open an issue. There is no private channel for security reports yet.