What causes "[Core Agent] Could not find port number." in google-gemini/gemini-cli?

Set CODER_AGENT_PORT to a fixed port so the env-var branch is taken instead of relying on address().port.

google-gemini/gemini-cli · error · Error

[Core Agent] Could not find port number.

Error message

[Core Agent] Could not find port number.

What it means

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.

Source

Thrown at packages/a2a-server/src/http/app.ts:419

    logger.error('[CoreAgent] Error during startup:', error);
    process.exit(1);
  }
}

export async function main() {
  try {
    const expressApp = await createApp();
    const port = Number(process.env['CODER_AGENT_PORT'] || 0);

    const server = expressApp.listen(port, 'localhost', () => {
      const address = server.address();
      let actualPort;
      if (process.env['CODER_AGENT_PORT']) {
        actualPort = process.env['CODER_AGENT_PORT'];
      } else if (address && typeof address !== 'string') {
        actualPort = address.port;
      } else {
        throw new Error('[Core Agent] Could not find port number.');
      }
      updateCoderAgentCardUrl(Number(actualPort));
      logger.info(
        `[CoreAgent] Agent Server started on http://localhost:${actualPort}`,
      );
      logger.info(
        `[CoreAgent] Agent Card: http://localhost:${actualPort}/.well-known/agent-card.json`,
      );
      logger.info('[CoreAgent] Press Ctrl+C to stop the server');
    });
  } catch (error) {
    logger.error('[CoreAgent] Error during startup:', error);
    process.exit(1);
  }
}

View on GitHub (pinned to 5024443c72)

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.

Example fix

# before
# CODER_AGENT_PORT unset; relies on address().port

# after
export CODER_AGENT_PORT=8080

Defensive patterns

Strategy: validation

Validate before calling

function resolveListenPort(): number {
  const p = process.env['CODER_AGENT_PORT'];
  if (p) return Number(p);
  // ephemeral fallback - caller must read address().port
  return 0;
}
// Prefer setting CODER_AGENT_PORT to avoid relying on address().port entirely.

Prevention

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.

When it happens

Trigger: 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).

Common situations: Edge binding failures on certain Node/OS combos; an environment where 'localhost' doesn't resolve; race where server.close runs before the listening callback.

Related errors

AI-assisted analysis of google-gemini/gemini-cli@5024443c72 (2026-08-12). Data as JSON: /api/errors/2a39e5aae1fa9518. Report an issue: GitHub.