{"record":{"id":"6f71bee63da60205","repo":"rohitg00/agentmemory","slug":"unknown-tool-toolname-local-fallback-supports","errorCode":null,"errorMessage":"Unknown tool: ${toolName} (local fallback supports only ${[...IMPLEMENTED_TOOLS].join(\", \")}; start an agentmemory server and set AGENTMEMORY_URL to use the full tool set)","messagePattern":"Unknown tool: (.+?) \\(local fallback supports only (.+?); start an agentmemory server and set AGENTMEMORY_URL to use the full tool set\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/mcp/standalone.ts","lineNumber":397,"sourceCode":"  const handle = await resolveHandle();\n  announceMode(handle);\n\n  // Tools the local InMemoryKV fallback doesn't implement: forward straight\n  // to the server. Local validation would otherwise raise \"Unknown tool\"\n  // (issue #234).\n  if (!IMPLEMENTED_TOOLS.has(toolName)) {\n    if (handle.mode === \"proxy\") {\n      try {\n        return await handleProxyGeneric(toolName, args, handle);\n      } catch (err) {\n        process.stderr.write(\n          `[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}\\n`,\n        );\n        invalidateHandle();\n        throw err;\n      }\n    }\n    throw new Error(\n      `Unknown tool: ${toolName} (local fallback supports only ${[...IMPLEMENTED_TOOLS].join(\", \")}; start an agentmemory server and set AGENTMEMORY_URL to use the full tool set)`,\n    );\n  }\n\n  const validated = validate(toolName, args);\n  if (handle.mode === \"proxy\") {\n    try {\n      return await handleProxy(validated, handle);\n    } catch (err) {\n      process.stderr.write(\n        `[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}; invalidating handle and falling back to local KV\\n`,\n      );\n      invalidateHandle();\n    }\n  }\n  return handleLocal(validated, kvInstance);\n}\n","sourceCodeStart":379,"sourceCodeEnd":415,"githubUrl":"https://github.com/rohitg00/agentmemory/blob/e04ba88819c365c9acf9d6661ea802143e728bd6/src/mcp/standalone.ts#L379-L415","documentation":"`handleToolCall` first validates the tool name against IMPLEMENTED_TOOLS (the locally implemented subset); if the name is not there it tries the proxy to the full server, and only when the proxy is unavailable or fails does it throw this enriched error. It tells you the tool is not implemented locally and lists the allowed local tools, directing you to start a server and set AGENTMEMORY_URL for the full set.","triggerScenarios":"Calling tools/call with a tool name outside IMPLEMENTED_TOOLS while no agentmemory server is reachable at AGENTMEMORY_URL (proxy call fails or is skipped). The validated name then falls through to the final throw at standalone.ts:397.","commonSituations":"CI or a fresh checkout where the daemon was never started; AGENTMEMORY_URL pointing at a dead port or wrong host so proxy calls fail; calling newer tools (e.g. audit/crystallize family) against an old standalone bundle running in reduced mode.","solutions":["Start the agentmemory daemon: `npx @agentmemory/agentmemory`, then set `AGENTMEMORY_URL` (e.g. http://localhost:49134) and retry.","Verify AGENTMEMORY_URL is reachable: `curl $AGENTMEMORY_URL/agentmemory/health`.","Restrict your tool calls to the locally implemented set printed in the error (IMPLEMENTED_TOOLS).","Update the standalone server package so IMPLEMENTED_TOOLS covers the tools your client lists."],"exampleFix":"// before\n// no daemon; AGENTMEMORY_URL unset or stale\ncallTool(\"memory_recall_by_concept\", { concept: \"auth\" });\n// after\n// terminal 1: npx @agentmemory/agentmemory\n// terminal 2:\nprocess.env.AGENTMEMORY_URL = \"http://localhost:49134\";\ncallTool(\"memory_recall_by_concept\", { concept: \"auth\" });","handlingStrategy":"validation","validationCode":"async function ensureServerReady(url = process.env.AGENTMEMORY_URL) {\n  if (!url) throw new Error(\"AGENTMEMORY_URL not set; full tool set unavailable\");\n  const res = await fetch(`${url}/agentmemory/health`, { signal: AbortSignal.timeout(2000) });\n  if (!res.ok) throw new Error(`agentmemory server unhealthy: ${res.status}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  return await callTool(tool, args);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith(\"Unknown tool:\")) {\n    await ensureServerReady(); // retry once with the full server\n    return await callTool(tool, args);\n  }\n  throw e;\n}","preventionTips":["Run a startup healthcheck against AGENTMEMORY_URL before issuing any tool calls.","Start the daemon as part of your dev script / docker-compose so it is never missing.","Pin AGENTMEMORY_URL in CI secrets and .env, never leave it unset.","Log IMPLEMENTED_TOOLS (printed in the error) and keep client tool usage within it when offline."],"tags":["mcp","unknown-tool","configuration","proxy-unreachable"],"backgroundTag":"unknown-tool-name","analyzedSha":"e04ba88819c365c9acf9d6661ea802143e728bd6","analyzedAt":"2026-08-30T01:07:40.754Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}