What causes "unknown override kind: ${override.kind}" in denoland/deno?

Use plain Node-style listen arguments: server.listen(port[, host]), server.listen("/path.sock") for unix sockets

denoland/deno · error · Error

unknown override kind: ${override.kind}

Error message

unknown override kind: ${override.kind}

What it means

Internal invariant violation in Deno's Node-compat HTTP address-override layer. getAddress() (ext/node/polyfills/internal/http/address_override.js) converts an address override into a Deno listen/connect address; if override.kind is not one of the supported kinds (inet, unix, vsock, tunnel) it falls through to the default branch and throws a plain Error with no code. Reaching it means an address shape the polyfill cannot map leaked into http/net APIs.

Source

Thrown at ext/node/polyfills/internal/http/address_override.js:101

}

// Translate an override record into the argument for denoListen().
function overrideToListenArgs(override) {
  switch (override.kind) {
    case KIND_TCP:
      return { hostname: override.host, port: override.port };
    case KIND_UNIX:
      return { transport: "unix", path: override.host };
    case KIND_VSOCK:
      return {
        transport: "vsock",
        cid: Number(override.host),
        port: override.port,
      };
    case KIND_TUNNEL:
      return { transport: "tunnel" };
    default:
      throw new Error(`unknown override kind: ${override.kind}`);
  }
}

// Minimal Socket-like Duplex wrapping a Deno.Conn. It exposes the
// subset of the net.Socket interface that connectionListener in
// _http_server.js actually uses.
class OverrideSocket extends Duplex {
  #conn;
  #closed = false;
  #initialChunk = null;
  #readBuf = new Uint8Array(64 * 1024);
  #timeoutMsecs = 0;
  #timeoutTimer = null;
  // Node's HTTP server uses these directly.
  isDenoServeAddressOverride = true;
  // Set by the alpn-routing dispatch (node:http2 servers) to the sniffed
  // protocol, mirroring what a TLS socket would report.
  alpnProtocol = undefined;

View on GitHub (pinned to 9ad36f7a2c)

Solutions

Use plain Node-style listen arguments: server.listen(port[, host]), server.listen("/path.sock") for unix sockets
Normalize any Deno address object to { port, host } or a path string before it reaches a Node API
Verify the same call works under node:http, then re-test on the latest Deno — if inputs are valid, report the bug upstream

Example fix

// before
const server = http.createServer(handler);
server.listen({ transport: "unix", path: "/tmp/s.sock" }); // unknown override kind

// after
const server = http.createServer(handler);
server.listen("/tmp/s.sock"); // Node-style unix socket path

Defensive patterns

Strategy: validation

Validate before calling

function isSupportedListenArg(a) {
  if (typeof a === "number" || typeof a === "string") return true; // port or path
  if (a && typeof a === "object") {
    return Number.isInteger(a.port) || typeof a.path === "string";
  }
  return false;
}

Try / catch

try {
  server.listen(addr);
} catch (err) {
  if (/unknown override kind/.test(err.message)) {
    // normalize addr to { port, host } or a path string and retry; else report upstream
  } else throw err;
}

Prevention

Pass Node-shaped listen arguments to Node APIs and Deno-shaped addresses to Deno APIs — never mix them
Keep the runtime current; address-override coverage improves each release

When it happens

Trigger: Calling server.listen() or http2.connect() with a Deno-shaped address object (e.g. { transport: "unix", path } or { transport: "vsock" }) instead of Node-style arguments; passing a Deno.listen() result into a Node http server; a tunnel/upgrade path producing an override with an unset kind field.

Common situations: Cross-runtime code mixing Deno-native listen options into node:http calls; polyfilling gaps where an override object is constructed by hand; older Deno versions whose address_override covers fewer kinds than the code assumes.

Related errors

AI-assisted analysis of denoland/deno@9ad36f7a2c (2026-08-20). Data as JSON: /api/errors/6134526667930802. Report an issue: GitHub.