oven-sh/bun · error · Error

Invalid UNIX path: ${path}

Error message

Invalid UNIX path: ${path}

What it means

Thrown by parseUnixPath() when the path passed to a UnixSignal debug-adapter server is neither an absolute filesystem string (starting with '/') nor a value the URL constructor can parse. The adapter must bind a concrete UNIX domain socket, so ambiguous or relative input is rejected up front. Note that on non-POSIX platforms (Windows) there is no absolute '/' path, so nearly any string fails or yields a useless pathname.

Source

Thrown at packages/bun-debug-adapter-protocol/src/debugger/signal.ts:92

   */
  close(): void {
    this.#server.close();
  }
}

export function randomUnixPath(): string {
  return join(tmpdir(), `${randomBytes(16).toString("hex")}.sock`);
}

function parseUnixPath(path: string | URL): string {
  if (typeof path === "string" && path.startsWith("/")) {
    return path;
  }
  try {
    const { pathname } = new URL(path);
    return pathname;
  } catch {
    throw new Error(`Invalid UNIX path: ${path}`);
  }
}

export type TCPSocketSignalEventMap = {
  "Signal.listening": [];
  "Signal.error": [Error];
  "Signal.closed": [];
  "Signal.received": [string];
  "Signal.Socket.closed": [socket: Socket];
  "Signal.Socket.connect": [socket: Socket];
};

export class TCPSocketSignal extends EventEmitter {
  #port: number;
  #server: ReturnType<typeof createServer>;
  #ready: Promise<void>;

  constructor(port: number) {

View on GitHub (pinned to 8c5296ac45)

Solutions

1. Pass an absolute path, e.g. join(tmpdir(), 'name.sock')
2. Pass a parseable URL string such as 'unix:///tmp/foo.sock' (the pathname is extracted and used)
3. On Windows use the TCP-based TCPSocketSignal class instead of UnixSignal
4. Omit the argument so randomUnixPath() generates a valid absolute path for you

Example fix

// before
new UnixSignal('./bun-debug.sock'); // relative path -> throws

// after
import { tmpdir } from 'node:os';
import { join } from 'node:path';
new UnixSignal(join(tmpdir(), 'bun-debug.sock'));

import { isAbsolute } from 'node:path';

function canParseUnixPath(path: string | URL): boolean {
  if (typeof path !== 'string') return path instanceof URL;
  if (path.startsWith('/')) return true;
  try { new URL(path); return true; } catch { return false; }
}

if (!canParseUnixPath(socketPath)) throw new TypeError(`bad unix socket path: ${String(socketPath)}`);

function isUnixSocketPath(path: unknown): path is string | URL {
  if (path instanceof URL) return true;
  if (typeof path !== 'string') return false;
  if (path.startsWith('/')) return true;
  try { new URL(path); return true; } catch { return false; }
}

When it happens

Trigger: Constructing new UnixSignal(path) with a relative string like './bun-debug.sock', a Windows path like 'C:\\sock' or '\\\\.\\pipe\\x', an empty string, or a string that makes new URL(path) throw (e.g. 'bun-debug.sock').

Common situations: Running the Bun VS Code debugger tooling on Windows where UNIX sockets are not filesystem paths; passing a cwd-relative socket path; passing a value that is neither string nor URL (e.g. a number from config).

Related errors

• Not supported: ${type}
• Executable not found: bunx or npx

AI-assisted analysis of oven-sh/bun@8c5296ac45 (2026-08-16). Data as JSON: /api/errors/cd6db297cf92e60b. Report an issue: GitHub.