{"record":{"id":"0bc01313726398ea","repo":"ruvnet/ruflo","slug":"not-found-0bc013","errorCode":null,"errorMessage":"not_found","messagePattern":"not_found","errorType":"http","errorClass":null,"httpStatus":404,"severity":"error","filePath":"v3/@claude-flow/plugin-agent-federation/src/a2a/well-known.ts","lineNumber":72,"sourceCode":" *   other path       → 404\n */\nexport function startAgentCardServer(\n  options: AgentCardServerOptions,\n): Promise<AgentCardServerHandle> {\n  const host = options.host ?? '127.0.0.1';\n  const path = options.path ?? A2A_WELL_KNOWN_PATH;\n  const maxAge = options.cacheMaxAgeSeconds ?? 300;\n\n  if (!isLoopbackHost(host) && options.allowNonLoopback !== true) {\n    return Promise.reject(new Error(\n      `A2A agent-card server: refusing non-loopback bind ${host} without allowNonLoopback: true (ADR-166)`,\n    ));\n  }\n\n  const server: Server = createServer((req, res) => {\n    const reqPath = (req.url ?? '').split('?')[0];\n    if (reqPath !== path) {\n      res.writeHead(404, { 'content-type': 'application/json' });\n      res.end(JSON.stringify({ error: 'not_found', agentCardPath: path }));\n      return;\n    }\n    if (req.method !== 'GET' && req.method !== 'HEAD') {\n      res.writeHead(405, { allow: 'GET, HEAD', 'content-type': 'application/json' });\n      res.end(JSON.stringify({ error: 'method_not_allowed' }));\n      return;\n    }\n    const card = options.getCard();\n    if (!card) {\n      res.writeHead(503, { 'content-type': 'application/json', 'retry-after': '5' });\n      res.end(JSON.stringify({ error: 'agent_card_not_ready' }));\n      return;\n    }\n    const body = JSON.stringify(card, null, 2);\n    const etag = `\"${createHash('sha256').update(body).digest('hex').slice(0, 32)}\"`;\n    if (req.headers['if-none-match'] === etag) {\n      res.writeHead(304, { etag });","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/plugin-agent-federation/src/a2a/well-known.ts#L54-L90","documentation":"JSON error body returned by the A2A agent-card server when the request path does not match the configured well-known agent-card path (default /.well-known/agent.json); the body names the expected agentCardPath and the response is a 404.","triggerScenarios":"Thrown at v3/@claude-flow/plugin-agent-federation/src/a2a/well-known.ts:72 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Request a resource that exists; verify the path/identifier against the service's published endpoints."],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}