denoland/deno · error · RangeError

Invalid port (out of range): ${maybePort}

Error message

Invalid port (out of range): ${maybePort}

What it means

RangeError from validatePort(): the port is a valid integer but outside the allowed range. Client APIs (Deno.connect, Deno.connectTls) require 1-65535; server APIs (Deno.listen, Deno.listenTls, Deno.listenDatagram) additionally accept 0, which asks the OS to assign a port.

Source

Thrown at ext/net/01_net.js:657

  // must always specify a port to connect to, so a missing port is left as-is
  // and rejected below.
  if (isServer && (maybePort === null || maybePort === undefined)) {
    maybePort = 0;
  }
  if (typeof maybePort !== "number" && typeof maybePort !== "string") {
    throw new TypeError(`Invalid port (expected number): ${maybePort}`);
  }
  if (maybePort === "") throw new TypeError("Invalid port: ''");
  const port = Number(maybePort);
  if (!NumberIsInteger(port)) {
    if (NumberIsNaN(port) && !NumberIsNaN(maybePort)) {
      throw new TypeError(`Invalid port: '${maybePort}'`);
    } else {
      throw new TypeError(`Invalid port: ${maybePort}`);
    }
  } else if (port < (isServer ? 0 : 1) || port > 65535) {
    // Servers may bind to port 0 (OS-assigned), clients may not connect to it.
    throw new RangeError(`Invalid port (out of range): ${maybePort}`);
  }
  return port;
}

function createListenDatagram(udpOpFn, unixOpFn) {
  return function listenDatagram(args) {
    switch (args.transport) {
      case "udp": {
        const port = validatePort(args.port, true);
        const { 0: rid, 1: addr } = udpOpFn(
          {
            hostname: args.hostname ?? "0.0.0.0",
            port,
          },
          args.reuseAddress ?? false,
          args.loopback ?? false,
        );
        addr.transport = "udp";

View on GitHub (pinned to 89f33cbef2)

Solutions

  1. Validate to 1-65535 for connects and 0-65535 for listens before the call
  2. If you wanted an OS-assigned port, remember only listeners accept 0 - clients simply connect to the server's port
  3. Re-check config parsing for typos such as 80800 or 6553 missing a digit

Example fix

// before
await Deno.connect({ hostname, port: config.port }); // config.port = 70000

// after
const { port } = config;
if (!(Number.isInteger(port) && port >= 1 && port <= 65535)) {
  throw new Error(`Port out of range: ${port}`);
}
await Deno.connect({ hostname, port });
Defensive patterns

Strategy: validation

Validate before calling

function portInRange(port: number, isServer: boolean): boolean {
  const min = isServer ? 0 : 1;
  return Number.isInteger(port) && port >= min && port <= 65535;
}

if (!portInRange(port, false)) throw new Error(`connect port out of range: ${port}`);
await Deno.connect({ hostname, port });

Type guard

function isClientPort(p: unknown): p is number {
  return typeof p === "number" && Number.isInteger(p) && p >= 1 && p <= 65535;
}

Prevention

When it happens

Trigger: Deno.connect({ port: 0 }) (0 is only valid for listeners); port: 65536; port: -1; port: 70000 from a misparsed config; Deno.listen({ port: -1 }).

Common situations: Off-by-one at the 65535/65536 boundary; using 0 to request an ephemeral source port on a client connect (unsupported); ports above 65535 copied from 'ephemeral range' docs; signed arithmetic overflow on 16-bit math.

Related errors

AI-assisted analysis of denoland/deno@89f33cbef2 (2026-08-16). Data as JSON: /api/errors/a21db3cebc7de9de. Report an issue: GitHub.