{"record":{"id":"efe43ab24351d8ab","repo":"thedotmack/claude-mem","slug":"missing-api-key","errorCode":"missing_api_key","errorMessage":"${toolName}: ${resolution.reason}","messagePattern":"\\$\\{toolName\\}: \\$\\{resolution\\.reason\\}","errorType":"exception","errorClass":"ServerClientError","httpStatus":null,"severity":"error","filePath":"src/servers/mcp-server.ts","lineNumber":213,"sourceCode":"function formatJsonResult(payload: unknown): { content: Array<{ type: 'text'; text: string }> } {\n  return {\n    content: [{\n      type: 'text' as const,\n      text: JSON.stringify(payload, null, 2),\n    }],\n  };\n}\n\nfunction requireServerForObservationTool(toolName: string): ServerAvailable {\n  const resolution = resolveServerToolContext();\n  if (!resolution) {\n    throw new ServerClientError(\n      'transport',\n      `${toolName} requires CLAUDE_MEM_RUNTIME=server. Current runtime is \"worker\"; use the existing search/timeline/get_observations tools for worker-mode memory access.`,\n    );\n  }\n  if (!resolution.available) {\n    throw new ServerClientError('missing_api_key', `${toolName}: ${resolution.reason}`);\n  }\n  return resolution;\n}\n\nfunction wrapHandler<Args>(\n  toolName: string,\n  execute: (args: Args) => Promise<{ content: Array<{ type: 'text'; text: string }> }>,\n): (args: Args) => Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {\n  return async (args: Args) => {\n    try {\n      return await execute(args);\n    } catch (error) {\n      const err = error instanceof Error ? error : new Error(String(error));\n      logger.warn('SYSTEM', `${toolName} failed`, undefined, err);\n      return formatToolError(error);\n    }\n  };\n}","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/thedotmack/claude-mem/blob/d8bc9755e74915e5c3b999181e10a67c889bce2a/src/servers/mcp-server.ts#L195-L231","documentation":"requireServerForObservationTool throws this ServerClientError (code 'missing_api_key') when the runtime resolves to 'server' mode but resolution.available is false — resolution.reason explains why, almost always that the required server API key (or equivalent credential/server URL) is absent. It means the runtime selection succeeded but the tool cannot authenticate to the claude-mem server.","triggerScenarios":"Calling a server-only observation tool while CLAUDE_MEM_RUNTIME=server is set but the server API key / credentials / endpoint configuration is missing or unusable, making resolveServerToolContext() return { available: false, reason }.","commonSituations":"Operator flipped CLAUDE_MEM_RUNTIME=server but never ran `claude-mem server api-key create` or didn't export the key env var; key var set in the wrong process scope; server URL misconfigured so the client can't build a valid request.","solutions":["Read `${toolName}: ${resolution.reason}` in the message — it names the exact missing/misconfigured item.","Create an API key with `claude-mem server api-key create` and export it in the MCP server's environment.","Confirm the server endpoint/URL configuration is present alongside the key.","Restart the MCP server after setting the credentials so the context is re-resolved."],"exampleFix":"// before\nCLAUDE_MEM_RUNTIME=server\n// after\nCLAUDE_MEM_RUNTIME=server\nCLAUDE_MEM_SERVER_API_KEY=<key from `claude-mem server api-key create`>\nCLAUDE_MEM_SERVER_URL=https://mem.example.com","handlingStrategy":"validation","validationCode":"function hasServerCredentials(env: NodeJS.ProcessEnv = process.env): boolean {\n  return (env.CLAUDE_MEM_RUNTIME ?? '').trim() === 'server'\n    && Boolean((env.CLAUDE_MEM_SERVER_API_KEY ?? '').trim());\n}","typeGuard":null,"tryCatchPattern":"try {\n  ctx = requireServerForObservationTool('observation_add');\n} catch (err) {\n  if (err instanceof ServerClientError && err.code === 'missing_api_key') {\n    // surface remediation: run `claude-mem server api-key create` and export the key\n  }\n  throw err;\n}","preventionTips":["Run `claude-mem server api-key create` as part of server onboarding and store the key in a secret manager.","Set the API key env var in the same process scope that launches the MCP server.","Pair every CLAUDE_MEM_RUNTIME=server rollout with a credential checklist (key + server URL).","Rotate keys on a schedule and update deployment secrets in the same change."],"tags":["authentication","api-key","configuration","mcp"],"backgroundTag":"missing-api-key","analyzedSha":"d8bc9755e74915e5c3b999181e10a67c889bce2a","analyzedAt":"2026-09-17T16:40:26.182Z","contentChangedAt":"2026-09-17T16:40:26.182Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}