Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

fix(cli): render backend-down as guidance instead of an undici stack trace (#333)

KageBinary8d4ba28f293e
diff --git a/ix-cli/src/cli/__tests__/errors.test.ts b/ix-cli/src/cli/__tests__/errors.test.ts
new file mode 100644
index 00000000..a55dbc22
--- /dev/null
+++ b/ix-cli/src/cli/__tests__/errors.test.ts
@@ -0,0 +1,223 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+ CliResolutionError,
+ CliUsageError,
+ formatFetchError,
+ isBackendUnreachable,
+ renderCliError,
+} from "../errors.js";
+
+/** Node's fetch shape: `TypeError: fetch failed` with the real error nested. */
+function fetchFailure(code: string): Error {
+ const err = new TypeError("fetch failed");
+ (err as { cause?: unknown }).cause = Object.assign(
+ new Error(`connect ${code} 127.0.0.1:8090`),
+ { code, errno: -111, syscall: "connect" },
+ );
+ return err;
+}
+
+/**
+ * The same shape for a socket that was established and then died.
+ *
+ * The classifier keys on the code alone, so as an input this differs from
+ * `fetchFailure` only in fields nothing reads. It is here to name the scenario
+ * the mid-flight codes stand for — it is not a phase discriminator, and a code
+ * moved into UNREACHABLE_CODES would not be caught by using this helper.
+ */
+function midFlightFailure(code: string): Error {
+ const err = new TypeError("fetch failed");
+ (err as { cause?: unknown }).cause = Object.assign(
+ new Error(`read ${code} 127.0.0.1:8090`),
+ { code, errno: -104, syscall: "read" },
+ );
+ return err;
+}
+
+/**
+ * renderCliError writes to stderr and then exits. It reaches stderr two ways —
+ * process.stderr.write directly, and console.error via renderStructuredError —
+ * so both are captured here. Exit is turned into a throw so asserting on the
+ * rendered output does not kill the test runner.
+ */
+function capture(fn: () => void): { out: string; exited: boolean } {
+ let out = "";
+ const write = vi
+ .spyOn(process.stderr, "write")
+ .mockImplementation((chunk: unknown) => {
+ out += String(chunk);
+ return true;
+ });
+ const log = vi
+ .spyOn(console, "error")
+ .mockImplementation((...args: unknown[]) => {
+ out += args.map(String).join(" ") + "\n";
+ });
+ const exit = vi.spyOn(process, "exit").mockImplementation(((): never => {
+ throw new Error("__exit__");
+ }) as never);
+
+ let exited = false;
+ try {
+ fn();
+ } catch (err) {
+ if ((err as Error).message === "__exit__") exited = true;
+ else throw err;
+ } finally {
+ write.mockRestore();
+ log.mockRestore();
+ exit.mockRestore();
+ }
+ return { out, exited };
+}
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe("isBackendUnreachable", () => {
+ it("detects a transport code nested under cause (Node fetch shape)", () => {
+ expect(isBackendUnreachable(fetchFailure("ECONNREFUSED"))).toBe(true);
+ expect(isBackendUnreachable(fetchFailure("EHOSTUNREACH"))).toBe(true);
+ expect(isBackendUnreachable(fetchFailure("UND_ERR_CONNECT_TIMEOUT"))).toBe(true);
+ });
+
+ it("detects a transport code set directly on the error", () => {
+ expect(isBackendUnreachable(Object.assign(new Error("nope"), { code: "ECONNREFUSED" }))).toBe(true);
+ });
+
+ it("does not claim unreachability for backend-authored errors", () => {
+ // The backend answered — it just answered with an error. That must keep
+ // rendering the real message rather than "start the backend".
+ expect(isBackendUnreachable(new Error('500: {"error":"boom","message":"kaput"}'))).toBe(false);
+ expect(isBackendUnreachable(new Error("something else"))).toBe(false);
+ });
+
+ it("tolerates null, undefined and non-error values", () => {
+ expect(isBackendUnreachable(null)).toBe(false);
+ expect(isBackendUnreachable(undefined)).toBe(false);
+ expect(isBackendUnreachable("a string")).toBe(false);
+ });
+
+ it("does not claim unreachability for a connection dropped mid-flight", () => {
+ // A connection that was working and then died is a different problem with a
+ // different remedy; "start the backend" is the wrong thing to say about it.
+ expect(isBackendUnreachable(midFlightFailure("ECONNRESET"))).toBe(false);
+ expect(isBackendUnreachable(midFlightFailure("ETIMEDOUT"))).toBe(false);
+ });
+
+ it("claims unreachability when the port accepts but nothing serves", () => {
+ // Measured shape of a container that is still booting, or a published port
+ // with a dead container behind it: undici accepts, gets a FIN, and reports
+ // "other side closed". That user does need `ix docker start` / `ix status`.
+ expect(isBackendUnreachable(fetchFailure("UND_ERR_SOCKET"))).toBe(true);
+ });
+});
+
+describe("renderCliError", () => {
+ it("renders backend-down as actionable guidance, never a stack trace", () => {
+ const { out, exited } = capture(() =>
+ renderCliError(fetchFailure("ECONNREFUSED"), false, "http://localhost:8090"),
+ );
+
+ expect(exited).toBe(true);
+ expect(out).toContain("Ix backend not reachable at http://localhost:8090");
+ expect(out).toContain("ix docker start");
+ // The whole point of the boundary: no Node internals, no absolute paths.
+ expect(out).not.toContain("node:internal");
+ expect(out).not.toContain("at async");
+ });
+
+ it("omits the endpoint when it cannot be resolved", () => {
+ const { out } = capture(() => renderCliError(fetchFailure("ECONNREFUSED"), false, undefined));
+ expect(out).toContain("Ix backend not reachable.");
+ });
+
+ it("unwraps a bare `fetch failed` so the transport cause is visible", () => {
+ const { out } = capture(() =>
+ renderCliError(Object.assign(new TypeError("fetch failed"), { cause: { message: "socket hang up" } })),
+ );
+ expect(out).toContain("socket hang up");
+ });
+
+ it("renders a structured backend error using its message and next step", () => {
+ const { out } = capture(() =>
+ renderCliError(new Error('404: {"error":"not_found","message":"No such entity","next":"Run ix map"}')),
+ );
+ expect(out).toContain("No such entity");
+ expect(out).toContain("Run ix map");
+ });
+
+ it("renders usage errors with their hint", () => {
+ const { out } = capture(() => renderCliError(new CliUsageError("Bad flag", "Try --kind class")));
+ expect(out).toContain("Bad flag");
+ expect(out).toContain("Try --kind class");
+ });
+
+ it("shows resolution detail only in debug mode", () => {
+ const err = new CliResolutionError("Ambiguous", "Narrow it down", "3 candidates");
+ expect(capture(() => renderCliError(err, false)).out).not.toContain("3 candidates");
+ expect(capture(() => renderCliError(err, true)).out).toContain("3 candidates");
+ });
+
+ it("appends the stack only in debug mode", () => {
+ const err = fetchFailure("ECONNREFUSED");
+ err.stack = "TypeError: fetch failed\n at node:internal/deps/undici/undici:14976:13";
+ expect(capture(() => renderCliError(err, false, "http://x")).out).not.toContain("node:internal");
+ expect(capture(() => renderCliError(err, true, "http://x")).out).toContain("node:internal");
+ });
+
+ it("does not tell a remote user to start Docker", () => {
+ // Pro syncs config.endpoint to a cloud instance; `ix docker start` cannot
+ // fix that endpoint and starts a backend the user is not pointed at.
+ const { out } = capture(() =>
+ renderCliError(fetchFailure("ECONNREFUSED"), false, "https://prod.cloud.ix-infra.com"),
+ );
+ expect(out).toContain("Ix backend not reachable at https://prod.cloud.ix-infra.com");
+ expect(out).not.toContain("ix docker start");
+ expect(out).toContain("ix config get endpoint");
+ });
+
+ it("keeps the docker remedy for a loopback endpoint", () => {
+ const { out } = capture(() =>
+ renderCliError(fetchFailure("ECONNREFUSED"), false, "http://127.0.0.1:8090"),
+ );
+ expect(out).toContain("ix docker start");
+ });
+
+ it("shows the cause chain in debug mode when the error carries no stack", () => {
+ // The case this module exists for: Node's fetch TypeError loses its frames
+ // across the async boundary, so `err.stack` alone renders nothing useful.
+ const err = fetchFailure("ECONNREFUSED");
+ err.stack = undefined;
+ const { out } = capture(() => renderCliError(err, true, "http://localhost:8090"));
+ expect(out).toContain("ECONNREFUSED");
+ });
+
+ it("does not print arbitrary error properties in debug mode", () => {
+ // This is the process-wide boundary. Dumping every own property of whatever
+ // was thrown would put credentials into output the user pastes into an issue.
+ const err = Object.assign(new Error("boom"), {
+ request: { headers: { authorization: "Bearer sk-SECRET-TOKEN" } },
+ });
+ const { out } = capture(() => renderCliError(err, true));
+ expect(out).toContain("boom");
+ expect(out).not.toContain("sk-SECRET-TOKEN");
+ });
+
+ it("does not throw on null or undefined", () => {
+ expect(capture(() => renderCliError(null)).exited).toBe(true);
+ expect(capture(() => renderCliError(undefined)).exited).toBe(true);
+ });
+});
+
+describe("formatFetchError", () => {
+ it("appends the nested cause code and message", () => {
+ expect(formatFetchError(fetchFailure("ECONNREFUSED"))).toContain("ECONNREFUSED");
+ });
+
+ it("passes non-fetch errors through untouched", () => {
+ expect(formatFetchError(new Error("plain"))).toBe("plain");
+ });
+});
diff --git a/ix-cli/src/cli/commands/upgrade.ts b/ix-cli/src/cli/commands/upgrade.ts
index 5c30ef3c..5554b3ef 100644
--- a/ix-cli/src/cli/commands/upgrade.ts
+++ b/ix-cli/src/cli/commands/upgrade.ts
@@ -63,7 +63,22 @@ async function fetchLatestRelease(repo: string): Promise<string | null> {
function readCache(): VersionCache | null {
try {
if (!existsSync(VERSION_CACHE)) return null;
- return JSON.parse(readFileSync(VERSION_CACHE, "utf-8"));
+ const parsed = JSON.parse(readFileSync(VERSION_CACHE, "utf-8"));
+ // JSON.parse only proves it is JSON, not that it is *this* shape. A cache
+ // file holding `{"latest": 123}` used to reach isNewer() and throw
+ // "latest.split is not a function", which surfaced as a successful command
+ // exiting 1. Every field that reaches isNewer() has to be checked, not just
+ // `latest` — the optional two get there behind a bare truthiness test.
+ const optionalString = (v: unknown) => v === undefined || typeof v === "string";
+ if (
+ typeof parsed?.latest !== "string" ||
+ typeof parsed?.checkedAt !== "number" ||
+ !optionalString(parsed.compassLatest) ||
+ !optionalString(parsed.backendLatest)
+ ) {
+ return null;
+ }
+ return parsed as VersionCache;
} catch {
return null;
}
@@ -163,6 +178,11 @@ export async function checkForUpdate(): Promise<void> {
if (hasCliUpdate || hasCompassUpdate || hasBackendUpdate) {
printUpdateNotice(current, latest, !!hasCompassUpdate, !!hasBackendUpdate);
}
+ }).catch(() => {
+ // Best-effort background check: it must never affect the command the user
+ // actually ran. Without this catch the floating promise would reach the
+ // process-level unhandledRejection handler and abort an otherwise
+ // successful command.
});
}
diff --git a/ix-cli/src/cli/errors.ts b/ix-cli/src/cli/errors.ts
index 9889ce16..97b6abf6 100644
--- a/ix-cli/src/cli/errors.ts
+++ b/ix-cli/src/cli/errors.ts
@@ -86,7 +86,11 @@ export function formatFetchError(err: unknown): string {
? e.message
: String(err);
- if (base.toLowerCase().includes("fetch failed") && e.cause) {
+ // "terminated" is what undici reports when a connection dies after the
+ // response headers — the commonest mid-flight shape, and one that carries no
+ // detail at all without this unwrap.
+ const lower = base.toLowerCase();
+ if ((lower.includes("fetch failed") || lower.includes("terminated")) && e.cause) {
const cause = e.cause as { code?: unknown; message?: unknown };
const parts: string[] = [];
if (typeof cause.code === "string" && cause.code.length > 0) {
@@ -103,7 +107,93 @@ export function formatFetchError(err: unknown): string {
return base;
}
-export function renderCliError(err: unknown, debug = false): void {
+/**
+ * Transport-level codes meaning "we did not get a working backend on the other
+ * end", as opposed to the backend answering with an error. Node's fetch
+ * surfaces these as `TypeError: fetch failed` with the real error under `cause`.
+ *
+ * `UND_ERR_SOCKET` ("other side closed") belongs here despite describing an
+ * established socket: measured, it is what you get from a port that accepts and
+ * then closes without answering — a container that is still booting, a dead
+ * container behind a published port, a port-forward to nothing. That user does
+ * need "start the backend, then check status".
+ *
+ * `ECONNRESET` and `ETIMEDOUT` are deliberately absent. Those are a connection
+ * that was working and then died, which is a different problem with a different
+ * remedy; they fall through to the generic path, which names the cause. The
+ * connect-phase half of `ETIMEDOUT` does not need special handling: undici's
+ * 10s connect timeout fires first and reports `UND_ERR_CONNECT_TIMEOUT`, which
+ * is already listed here.
+ */
+const UNREACHABLE_CODES = new Set([
+ "ECONNREFUSED",
+ "ENOTFOUND",
+ "EHOSTUNREACH",
+ "ENETUNREACH",
+ "EAI_AGAIN",
+ "UND_ERR_CONNECT_TIMEOUT",
+ "UND_ERR_SOCKET",
+]);
+
+function isUnreachableCode(e: { code?: unknown } | null | undefined): boolean {
+ return typeof e?.code === "string" && UNREACHABLE_CODES.has(e.code);
+}
+
+/** True for an endpoint served from this machine, where `ix docker start` applies. */
+function isLocalEndpoint(endpoint?: string): boolean {
+ if (!endpoint) return true; // unresolved endpoint defaults to the local install
+ return /^\w+:\/\/(localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0)(:\d+)?(\/|$)/i.test(endpoint);
+}
+
+/**
+ * Under IX_DEBUG, print the error *and its cause chain*.
+ *
+ * `err.stack` alone is empty for the very case this module exists to handle:
+ * Node's fetch rejects with a `TypeError: fetch failed` whose frames are lost
+ * across the async boundary, so the whole diagnostic — ECONNREFUSED vs
+ * ENOTFOUND vs a TLS failure — lives in `err.cause`. Printing only the stack
+ * meant `IX_DEBUG=1` emitted one useless line for a backend-down error.
+ *
+ * Walks the chain by hand rather than handing the error to `util.inspect`.
+ * This is the process-wide error boundary, and inspect prints every own
+ * property of whatever was thrown; Pro holds a tunnel JWT and a long-lived
+ * refresh token, so the day something throws an error carrying its own request
+ * we would print credentials into output the user is about to paste into an
+ * issue. Only stack, message and code are ever emitted.
+ */
+function writeDebugDetail(err: unknown): void {
+ const lines: string[] = [];
+ const seen = new Set<unknown>();
+ let cur: unknown = err;
+
+ while (cur !== null && cur !== undefined && !seen.has(cur)) {
+ seen.add(cur);
+ const e = cur as { stack?: unknown; message?: unknown; code?: unknown; cause?: unknown };
+ const code = typeof e.code === "string" ? `${e.code}: ` : "";
+ const body =
+ typeof e.stack === "string" && e.stack.length > 0
+ ? `${code}${e.stack}`
+ : `${code}${typeof e.message === "string" ? e.message : String(cur)}`;
+ lines.push(lines.length === 0 ? body : ` [cause] ${body}`);
+ cur = typeof cur === "object" ? e.cause : undefined;
+ }
+
+ process.stderr.write(chalk.dim(`${lines.length > 0 ? lines.join("\n") : String(err)}\n`));
+}
+
+/**
+ * True when the error is a failure to reach the backend at all. This is by far
+ * the most common failure for a fresh install — the CLI is on PATH but the
+ * Docker backend was never started — so it gets its own actionable message
+ * instead of an undici stack trace.
+ */
+export function isBackendUnreachable(err: unknown): boolean {
+ const e = err as { code?: unknown; cause?: unknown } | null | undefined;
+ if (isUnreachableCode(e)) return true;
+ return isUnreachableCode(e?.cause as { code?: unknown } | null | undefined);
+}
+
+export function renderCliError(err: unknown, debug = false, endpoint?: string): void {
if (err instanceof CliUsageError || err instanceof CliResolutionError) {
process.stderr.write(chalk.red(`Error: ${err.message}\n`));
if (err.hint) {
@@ -116,12 +206,35 @@ export function renderCliError(err: unknown, debug = false): void {
}
const e = err as any;
- const msg = e?.message ?? String(err);
- process.stderr.write(chalk.red(`Error: ${msg}\n`));
- if (debug && e?.stack) {
- process.stderr.write(chalk.dim(`${e.stack}\n`));
+ if (isBackendUnreachable(err)) {
+ renderStructuredError({
+ error: "backend_unreachable",
+ message: `Ix backend not reachable${endpoint ? ` at ${endpoint}` : ""}.`,
+ // `ix docker start` only fixes a backend this machine is supposed to run.
+ // Pro points `config.endpoint` at a cloud instance, where that advice is
+ // both useless and actively wrong — it starts a backend you aren't using.
+ next: isLocalEndpoint(endpoint)
+ ? "Start it with `ix docker start`, then check `ix status`."
+ : "Check your network, and that the endpoint is right (`ix config get endpoint`).",
+ });
+ if (debug) writeDebugDetail(err);
+ process.exit(1);
+ }
+
+ const structured = typeof e?.message === "string" ? parseBackendError(e.message) : null;
+ if (structured) {
+ renderStructuredError(structured);
+ if (debug) writeDebugDetail(err);
+ process.exit(1);
}
+ // formatFetchError unwraps `fetch failed` so the transport cause is visible
+ // rather than being hidden behind a message that says nothing.
+ const msg = err === null || err === undefined ? String(err) : formatFetchError(err);
+ process.stderr.write(chalk.red(`Error: ${msg}\n`));
+
+ if (debug) writeDebugDetail(err);
+
process.exit(1);
}
diff --git a/ix-cli/src/cli/main.ts b/ix-cli/src/cli/main.ts
index 4ca63726..582e6ef6 100644
--- a/ix-cli/src/cli/main.ts
+++ b/ix-cli/src/cli/main.ts
@@ -4,6 +4,8 @@ import { registerOssCommands, registerProStubs } from "./register/oss.js";
import { tryLoadProCommands } from "./register/pro-loader.js";
import { buildHelpText } from "./help-text.js";
import { checkForUpdate } from "./commands/upgrade.js";
+import { renderCliError } from "./errors.js";
+import { getEndpoint } from "./config.js";
import { readFileSync } from "fs";
import { join, dirname } from "path";
@@ -32,6 +34,30 @@ try {
cliVersion = pkg.version || "0.0.0";
} catch {}
+// Set IX_DEBUG=1 to append stack traces to any rendered error.
+const debug = process.env.IX_DEBUG === "1";
+
+// Resolving the endpoint reads config off disk, which can itself fail. An
+// error renderer must never throw, so failure here just drops the endpoint
+// from the message rather than replacing one crash with another.
+function safeEndpoint(): string | undefined {
+ try {
+ return getEndpoint();
+ } catch {
+ return undefined;
+ }
+}
+
+// Last line of defence. Without these, any rejection escaping a command — most
+// commonly the backend not running — reaches Node's default handler and prints
+// an undici stack trace that exposes internal paths and tells the user nothing.
+process.on("unhandledRejection", (err: unknown) => {
+ renderCliError(err, debug, safeEndpoint());
+});
+process.on("uncaughtException", (err: unknown) => {
+ renderCliError(err, debug, safeEndpoint());
+});
+
const program = new Command();
program
.name("ix")
@@ -60,8 +86,19 @@ registerOssCommands(program);
// Check for updates (non-blocking, cached 1hr) — skip for upgrade command itself
const args = process.argv.slice(2);
if (args[0] !== "upgrade") {
- checkForUpdate();
+ // Deliberately not awaited — but it must still be caught here. The catch
+ // inside checkForUpdate only guards its inner fetch chain; the function's
+ // own promise covers the synchronous cached-read path, and a corrupt
+ // ~/.ix/.version-check.json makes that throw. Uncaught, the new
+ // unhandledRejection handler then aborts a command that already succeeded.
+ checkForUpdate().catch(() => {});
}
- program.parse();
+ // parseAsync (not parse) so rejections from async action handlers surface
+ // here instead of floating off as unhandled rejections.
+ try {
+ await program.parseAsync();
+ } catch (err) {
+ renderCliError(err, debug, safeEndpoint());
+ }
})();