> ## Documentation Index > Fetch the complete documentation index at: https://docs.claw-link.dev/llms.txt > Use this file to discover all available pages before exploring further. # How to Fix “Tool Not Found” in OpenClaw > Troubleshoot the 'Tool not found' error in OpenClaw, including stale sessions, post-update drift, missing tool catalogs, and plugin/runtime state problems. OpenClaw lobster logo *“Tool not found” is one of those errors that sounds precise while telling you almost nothing useful. It feels specific. In practice, it is usually a label slapped onto several different failure modes.* If OpenClaw says **"Tool not found"**, do **not** assume there is one universal fix. That error usually means one of these: * the current chat is using a stale tool catalog * the gateway/runtime state changed after an update or restart * plugin-backed tools are no longer surfacing correctly * the expected tool path is missing in the currently active runtime * a version or config mismatch made previously available tools disappear This page is the diagnostic version, not the fairy-tale version. > Search icon > > **Fast rule:** if this started after an update or restart, suspect stale session or runtime/tool registry drift before anything more exotic. ## Search icon At a glance * `Tool not found` is usually a **multi-cause symptom**. * Start with `openclaw status` and `openclaw gateway status --json`. * Always retry in a **fresh chat** before assuming the tool is gone globally. * If the issue began after a restart or update, prioritize tool catalog and runtime-state checks. ## What this error usually means Users usually hit this in one of these ways: * a workflow that used to work now fails with `Tool not found` * a plugin-backed tool no longer appears callable * the assistant references tool execution, but the runtime rejects it * the error started after a gateway restart, update, or rollback That means the useful question is not: > “Where is the missing tool?” It is: > “Why does the current runtime think that tool does not exist?” ## Fastest troubleshooting flow Use this order. ## 1) Check overall status first Run: ```bash theme={null} openclaw status ``` Then: ```bash theme={null} openclaw gateway status --json ``` You are looking for clues like: * plugin/runtime load issues * unhealthy gateway state * config validation failures * weirdness introduced by update/rollback drift If status is already unhealthy, fix that first. Do not over-focus on the tool name. ## 2) Retry the exact same task in a fresh chat This matters more than people want it to. A stale chat can keep an old tool catalog alive even when the runtime has changed. So if you see `Tool not found`: * start a new chat * retry the same exact task If the new chat works, the “missing tool” was probably not globally missing at all. The old session was stale. ## 3) Ask whether this started after a restart, update, or rollback This is one of the highest-signal branches. If the error began after: * `openclaw gateway restart` * an OpenClaw upgrade * a rollback to an older version * plugin/config changes …then runtime or config drift is a prime suspect. That is especially true if tools worked before and disappeared suddenly. ## 4) Check whether the missing tool depends on plugin state Some `Tool not found` cases are really plugin surfacing problems. Ask: * is the tool from a plugin-backed path? * did plugin config or allowlist change? * did the gateway reload after installation or config edits? * is the current chat older than the plugin state now running? If yes, also read: * `Plugin Installed but Tools Don’t Appear in OpenClaw` ## 5) Inspect config/version mismatch if the error followed a rollback or upgrade A newer version can write config that an older version does not fully understand. Or a version change can leave runtime expectations out of sync with what the current process actually exposes. If that sounds plausible, inspect: ```text theme={null} ~/.openclaw/openclaw.json ``` And verify it still matches the version/runtime you are actually running. ## Common root causes ## Root cause 1: stale session / stale tool catalog Symptoms: * old chat throws `Tool not found` * fresh chat behaves normally * issue appeared after updates, plugin changes, or runtime reloads Fix: * start a fresh chat * retry the exact task there ## Root cause 2: runtime or gateway registry drift after restart Symptoms: * tools worked before restart * after restart, tool lookup fails * runtime appears alive, but tool calls break Fix: * check `openclaw status` * check `openclaw gateway status --json` * restart cleanly again if needed * re-test in a fresh chat ## Root cause 3: post-update version/config mismatch Symptoms: * issue started after upgrading or rolling back * some tools vanished unexpectedly * status or startup hints at config mismatch Fix: * inspect `~/.openclaw/openclaw.json` * confirm config matches the running version * review the post-update troubleshooting flow ## Root cause 4: plugin-backed tools stopped surfacing Symptoms: * tool belongs to plugin-backed behavior * install looks fine, but the runtime does not expose it * fresh session behavior differs from older chat behavior Fix: * verify plugin config or allowlist * restart the gateway * test in a fresh chat ## Root cause 5: wrong runtime expectation Symptoms: * user expects a tool path that is not active in the current setup * plugin, ACP, and normal assistant tool paths are getting mixed together Fix: * confirm which runtime path the workflow actually depends on * debug that path specifically instead of the error label ## Practical checklist Use this order: ### 1. Run `openclaw status` ### 2. Run `openclaw gateway status --json` ### 3. Retry the same task in a fresh chat ### 4. Check whether the issue started after restart/update/rollback ### 5. If plugin-backed, verify plugin config and reload state ### 6. Inspect config drift if version mismatch is plausible ## How to tell whether this is really a stale-session problem It probably is if: * the error appears only in an older chat * the issue started after updating, restarting, or changing plugins * a fresh chat behaves differently It is probably **not only** stale-session if: * status is broadly unhealthy * all contexts fail the same way * startup/config validation is already broken ## Common mistakes ### Treating `Tool not found` as one bug with one fix It is not. That is the whole trick. ### Restarting things without checking whether the current chat is stale Very common waste of time. ### Assuming the tool disappeared globally because one workflow failed Maybe. But maybe the old session is lying to you. ### Ignoring update or rollback timing If the timing lines up, pay attention. ## Final thought `Tool not found` is usually not a mystery about the tool. It is a mismatch between: * the tool catalog the session thinks exists * the runtime state currently loaded * the plugin/config/version state actually running Once you look at it that way, the error gets a lot less mystical and a lot more fixable. ## Related pages * `OpenClaw Not Responding? Start Here` * `OpenClaw Not Responding After an Update? Start Here` * `Plugin Installed but Tools Don’t Appear in OpenClaw` * `Why OpenClaw Says It Will Act but Doesn’t Complete the Task`