{"record":{"id":"2a39e5aae1fa9518","repo":"google-gemini/gemini-cli","slug":"core-agent-could-not-find-port-number","errorCode":null,"errorMessage":"[Core Agent] Could not find port number.","messagePattern":"\\[Core Agent\\] Could not find port number\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/a2a-server/src/http/app.ts","lineNumber":419,"sourceCode":"    logger.error('[CoreAgent] Error during startup:', error);\n    process.exit(1);\n  }\n}\n\nexport async function main() {\n  try {\n    const expressApp = await createApp();\n    const port = Number(process.env['CODER_AGENT_PORT'] || 0);\n\n    const server = expressApp.listen(port, 'localhost', () => {\n      const address = server.address();\n      let actualPort;\n      if (process.env['CODER_AGENT_PORT']) {\n        actualPort = process.env['CODER_AGENT_PORT'];\n      } else if (address && typeof address !== 'string') {\n        actualPort = address.port;\n      } else {\n        throw new Error('[Core Agent] Could not find port number.');\n      }\n      updateCoderAgentCardUrl(Number(actualPort));\n      logger.info(\n        `[CoreAgent] Agent Server started on http://localhost:${actualPort}`,\n      );\n      logger.info(\n        `[CoreAgent] Agent Card: http://localhost:${actualPort}/.well-known/agent-card.json`,\n      );\n      logger.info('[CoreAgent] Press Ctrl+C to stop the server');\n    });\n  } catch (error) {\n    logger.error('[CoreAgent] Error during startup:', error);\n    process.exit(1);\n  }\n}\n","sourceCodeStart":401,"sourceCodeEnd":435,"githubUrl":"https://github.com/google-gemini/gemini-cli/blob/5024443c7217464a66e98f80d73172a26440bd8f/packages/a2a-server/src/http/app.ts#L401-L435","documentation":"Thrown inside the express.listen callback when neither CODER_AGENT_PORT is set nor the server.address() returns an Address object. With port 0 (ephemeral) the OS assigns a port surfaced via server.address().port; if address() returns a string (Unix socket) or null (closed socket), the executor cannot determine the bound port and cannot update the agent-card URL.","triggerScenarios":"expressApp.listen succeeds but server.address() returns null or a string path. Reachable if the listen 'localhost' hostname fails to bind in a way that still invokes the callback with a non-object address, or if the socket was closed between bind and callback. The error propagates to the outer try/catch which calls process.exit(1).","commonSituations":"Edge binding failures on certain Node/OS combos; an environment where 'localhost' doesn't resolve; race where server.close runs before the listening callback.","solutions":["Set CODER_AGENT_PORT to a fixed port so the env-var branch is taken instead of relying on address().port.","Verify 'localhost' resolves on the host (IPv6/IPv4 issues); consider binding to 127.0.0.1.","Check that nothing closes the server synchronously after listen.","Upgrade Node - some old versions had address() timing bugs."],"exampleFix":"# before\n# CODER_AGENT_PORT unset; relies on address().port\n\n# after\nexport CODER_AGENT_PORT=8080","handlingStrategy":"validation","validationCode":"function resolveListenPort(): number {\n  const p = process.env['CODER_AGENT_PORT'];\n  if (p) return Number(p);\n  // ephemeral fallback - caller must read address().port\n  return 0;\n}\n// Prefer setting CODER_AGENT_PORT to avoid relying on address().port entirely.","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set CODER_AGENT_PORT to a fixed port in production.","Verify 'localhost' resolves (IPv4/IPv6) on the host.","Don't call server.close() before the listening callback fires.","Read server.address() only inside the listening callback, not after."],"tags":["http-server","startup","port-binding","env-vars"],"backgroundTag":null,"analyzedSha":"5024443c7217464a66e98f80d73172a26440bd8f","analyzedAt":"2026-08-12T06:01:53.711Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}