Capture privacy-scoped Docker startup failures after setup handoff

Author: msukkari

CHANGELOG.md

@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- Added privacy-scoped setup wizard funnel telemetry with deployment identity handoff, Node.js 20.20.0 support, and cross-platform end-to-end test coverage. [#1653](https://github.com/sourcebot-dev/sourcebot/pull/1653)
+- Added privacy-scoped setup wizard funnel and Docker startup-failure telemetry with deployment identity handoff, Node.js 20.20.0 support, and cross-platform end-to-end test coverage. [#1653](https://github.com/sourcebot-dev/sourcebot/pull/1653)
 
 ## [5.1.13] - 2026-09-12
 

packages/setupWizard/src/dockerStartFailure.ts

@@ -0,0 +1,55 @@
+import { stripVTControlCharacters } from 'node:util';
+import type { Events } from './telemetryEvents.js';
+
+type Reason = Events['start_failed']['failureReason'];
+
+// Docker exposes an exit status, not structured error reasons, for compose up.
+// Recognize only specific CLI/daemon diagnostics locally. Never serialize output,
+// captures, paths, image names, container names or IDs into an event.
+export class DockerStartFailure {
+    private pending = '';
+    private detected: Reason = 'unknown';
+
+    write(chunk: Buffer): void {
+        // Bound retained output even for a long-running foreground Compose process.
+        const lines = (this.pending + chunk.toString()).split(/[\r\n]/);
+        this.pending = (lines.pop() ?? '').slice(-8192);
+        for (const line of lines) {
+            this.classify(line.slice(-8192));
+        }
+    }
+
+    reason(): Reason {
+        this.classify(this.pending);
+        this.pending = '';
+        return this.detected;
+    }
+
+    private classify(raw: string): void {
+        if (this.detected !== 'unknown') {
+            return;
+        }
+        const line = stripVTControlCharacters(raw).trim();
+        // Attached application logs are not Docker diagnostics.
+        if (line.includes(' | ')) {
+            return;
+        }
+        const daemon = /^Error response from daemon:/i.test(line);
+        if (daemon && /container name .+ is already in use by container/i.test(line)) {
+            this.detected = 'container_name_conflict';
+        } else if (daemon && /port is already allocated|address already in use/i.test(line)) {
+            this.detected = 'port_conflict';
+        } else if (
+            /^(?:Error response from daemon:|unable to get image|pull access denied|failed to resolve reference)/i.test(line) &&
+            /pull access denied|manifest unknown|manifest for .+ not found|failed to resolve reference|no matching manifest|toomanyrequests|unauthorized: authentication required/i.test(line)
+        ) {
+            this.detected = 'image_pull_failed';
+        } else if (daemon && /invalid mount config|mounts denied|error while creating mount source path|invalid volume specification/i.test(line)) {
+            this.detected = 'mount_failed';
+        } else if (/^(?:Cannot connect to the Docker daemon|error during connect:|permission denied while trying to connect to the Docker daemon|docker: ['"]?compose['"]? is not a docker command)/i.test(line)) {
+            this.detected = 'docker_unavailable';
+        } else if (/^(?:validating .+:|no configuration file provided:|yaml: line \d+:|services\..+:|service .+ refers to undefined (?:volume|network) .+: invalid compose project)/i.test(line)) {
+            this.detected = 'compose_configuration';
+        }
+    }
+}

packages/setupWizard/src/index.ts

@@ -15,6 +15,7 @@ import {
     dockerOutcome,
 } from './telemetrySummary.js';
 import { Docker } from './docker.js';
+import { DockerStartFailure } from './dockerStartFailure.js';
 import type { CodeSourceSummary, Events } from './telemetryEvents.js';
 import net from 'node:net';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
@@ -891,7 +892,9 @@ async function main() {
         deploymentIdentityAction: deploymentIdentity.action,
         totalDurationMs: 0,
     };
-    const complete = () => lifecycle.complete({ ...completion, totalDurationMs: lifecycle.telemetry.elapsed() });
+    const complete = (keepTelemetryOpen = false) => lifecycle.complete(
+        { ...completion, totalDurationMs: lifecycle.telemetry.elapsed() }, keepTelemetryOpen,
+    );
     if (downloadedCompose && !leftDeploymentRunning) {
         const startNow = await confirm({
             message: hasPortConflicts
@@ -910,10 +913,13 @@ async function main() {
             const readiness = new AbortController();
             const releaseReadiness = lifecycle.own(() => readiness.abort());
             let spawned = false;
+            const startFailure = new DockerStartFailure();
             await new Promise<void>((resolve) => {
                 const child = lifecycle.child(
-                    spawn('docker', ['compose', 'up'], { stdio: 'inherit', detached: process.platform !== 'win32' }),
+                    spawn('docker', ['compose', 'up'], { stdio: ['inherit', 'inherit', 'pipe'], detached: process.platform !== 'win32' }),
                 );
+                child.stderr?.pipe(process.stderr, { end: false });
+                child.stderr?.on('data', (chunk: Buffer) => startFailure.write(chunk));
                 child.once('spawn', () => {
                     if (lifecycle.interrupted) {
                         child.kill();
@@ -922,19 +928,34 @@ async function main() {
                     spawned = true;
                     completion.sourcebotStartOutcome = 'spawned';
                     completion.completionMode = 'sourcebot_start_spawned';
-                    void complete();
+                    // Complete the setup handoff now, but keep diagnostics available
+                    // until Compose exits or the user interrupts it.
+                    void complete(true);
                     void openBrowserWhenReady(
                         SOURCEBOT_URL,
                         AbortSignal.any([lifecycle.signal, readiness.signal]),
                     ).catch(() => {});
                 });
-                child.once('close', () => {
+                child.once('close', (code, signal) => {
                     readiness.abort();
+                    if (spawned && code !== 0 && signal !== 'SIGINT' && signal !== 'SIGTERM') {
+                        const reason = startFailure.reason();
+                        lifecycle.startFailed({
+                            failurePhase: 'compose_exit',
+                            failureCategory: reason === 'docker_unavailable' ? 'docker_unavailable' : 'docker_command',
+                            failureReason: reason,
+                        });
+                    }
                     resolve();
                 });
                 child.once('error', (error: NodeJS.ErrnoException) => {
                     readiness.abort();
                     if (!lifecycle.interrupted) {
+                        lifecycle.startFailed({
+                            failurePhase: 'spawn',
+                            failureCategory: error.code === 'ENOENT' || error.code === 'EACCES' ? 'docker_unavailable' : 'process_spawn',
+                            failureReason: error.code === 'ENOENT' || error.code === 'EACCES' ? 'docker_unavailable' : 'unknown',
+                        });
                         lifecycle.fail(
                             error.code === 'ENOENT' || error.code === 'EACCES' ? 'docker_unavailable' : 'process_spawn',
                             true,

packages/setupWizard/src/lifecycle.ts

@@ -18,6 +18,7 @@ export class Lifecycle {
     terminal?: 'completed' | 'cancelled' | 'failed';
     interrupted = false;
     private installed = false;
+    private startFailureCaptured = false;
     constructor(readonly telemetry = new Telemetry()) {}
     get signal(): AbortSignal {
         return this.controller.signal;
@@ -89,13 +90,22 @@ export class Lifecycle {
             recoverable,
         });
     }
-    async complete(properties: Events['completed']): Promise<void> {
+    startFailed(properties: Events['start_failed']): void {
+        if (this.interrupted || this.startFailureCaptured || (this.terminal && this.terminal !== 'completed')) {
+            return;
+        }
+        this.startFailureCaptured = true;
+        this.telemetry.capture('start_failed', properties);
+    }
+    async complete(properties: Events['completed'], keepTelemetryOpen = false): Promise<void> {
         if (this.terminal || this.interrupted) {
             return;
         }
         this.terminal = 'completed';
         this.telemetry.capture('completed', properties);
-        await this.telemetry.shutdown();
+        if (!keepTelemetryOpen) {
+            await this.telemetry.shutdown();
+        }
     }
     async decline(reason: Events['cancelled']['reason']): Promise<void> {
         if (!this.terminal) {

packages/setupWizard/src/telemetryEvents.ts

@@ -310,6 +310,19 @@ export const eventSchemas = {
         ),
     },
     failed: { stage, failureCategory: category, recoverable: boolean },
+    start_failed: {
+        failurePhase: choice('spawn', 'compose_exit'),
+        failureCategory: choice('docker_unavailable', 'process_spawn', 'docker_command'),
+        failureReason: choice(
+            'container_name_conflict',
+            'port_conflict',
+            'image_pull_failed',
+            'mount_failed',
+            'compose_configuration',
+            'docker_unavailable',
+            'unknown',
+        ),
+    },
 };
 export type EventName = keyof typeof eventSchemas;
 export type Events = { [K in EventName]: Fields<(typeof eventSchemas)[K]> };

packages/setupWizard/tests/approvedSchema.json

@@ -568,6 +568,21 @@
       ]
     }
   },
+  "start_failed": {
+    "failurePhase": { "enum": ["spawn", "compose_exit"] },
+    "failureCategory": { "enum": ["docker_unavailable", "process_spawn", "docker_command"] },
+    "failureReason": {
+      "enum": [
+        "container_name_conflict",
+        "port_conflict",
+        "image_pull_failed",
+        "mount_failed",
+        "compose_configuration",
+        "docker_unavailable",
+        "unknown"
+      ]
+    }
+  },
   "failed": {
     "stage": {
       "enum": [

packages/setupWizard/tests/e2e/docker.test.mjs

@@ -93,9 +93,66 @@ test('failed spawn offers manual steps and completes after recoverable failures'
     });
     assert.equal(p(result, 'completed').sourcebotStartOutcome, 'spawn_failed');
     assert.equal(p(result, 'completed').completionMode, 'sourcebot_start_failed');
+    assert.equal(result.events.filter(e => e.event === 'setup_sourcebot_start_failed').length, 1);
+    assert.deepEqual(
+        ['failurePhase', 'failureCategory', 'failureReason'].map(key => p(result, 'start_failed')[key]),
+        ['spawn', 'docker_unavailable', 'docker_unavailable'],
+    );
     assert.ok(result.events.filter(e => e.event === 'setup_sourcebot_failed').every(e => e.properties.recoverable));
 });
 
+for (const [reason, diagnostic] of [
+    ['container_name_conflict', 'Error response from daemon: Conflict. The container name "/canary-sensitive-container" is already in use by container "canary-sensitive-id".'],
+    ['port_conflict', 'Error response from daemon: driver failed programming external connectivity: Bind for canary-sensitive-address failed: port is already allocated'],
+    ['image_pull_failed', 'Error response from daemon: pull access denied for canary-sensitive-image, repository does not exist or may require docker login'],
+    ['mount_failed', 'Error response from daemon: invalid mount config for type "bind": bind source path does not exist: canary-sensitive-path'],
+    ['compose_configuration', 'validating canary-sensitive-path: services.sourcebot Additional property canary-sensitive is not allowed'],
+    ['docker_unavailable', 'Cannot connect to the Docker daemon at canary-sensitive-socket. Is the docker daemon running?'],
+    ['unknown', 'canary-sensitive-unrecognized-error'],
+    ['unknown', 'canary-sensitive-app | Error response from daemon: pull access denied for canary-sensitive-image'],
+]) {
+    test(`post-handoff start failure: ${reason} (${diagnostic.slice(0, 24)})`, async () => {
+        const result = await scenario(packed, { docker: { start: { stderrChunks: [diagnostic.slice(0, 17), diagnostic.slice(17)], delayMs: 1100 } } }, async d => {
+            await initial(d);
+            await d.answer('Start Sourcebot now?', 'y');
+            await d.wait(diagnostic);
+        });
+        const failures = result.events.filter(e => e.event === 'setup_sourcebot_start_failed');
+        assert.equal(failures.length, 1);
+        assert.equal(failures[0].properties.failurePhase, 'compose_exit');
+        assert.equal(failures[0].properties.failureReason, reason);
+        assert.equal(failures[0].properties.failureCategory, reason === 'docker_unavailable' ? 'docker_unavailable' : 'docker_command');
+        const completed = result.events.find(e => e.event === 'setup_sourcebot_completed');
+        assert.ok(result.events.indexOf(completed) < result.events.indexOf(failures[0]));
+        assert.equal(failures[0].distinct_id, completed.distinct_id);
+        assert.equal(result.events.filter(e => e.event === 'setup_sourcebot_completed').length, 1);
+        assert.equal(result.events.some(e => e.event === 'setup_sourcebot_cancelled'), false);
+        assert.equal(result.exitCode, 0, 'Telemetry must not change existing CLI exit behavior');
+    });
+}
+
+for (const termination of [{ exitCode: 0 }, { signal: 'SIGINT' }, { signal: 'SIGTERM' }]) {
+    test(`normal Compose termination is not a start failure: ${JSON.stringify(termination)}`, { skip: process.platform === 'win32' && !!termination.signal }, async () => {
+        const result = await scenario(packed, { docker: { start: { ...termination, stderrChunks: ['Error response from daemon: pull access denied for canary-sensitive-image\n'] } } }, async d => {
+            await initial(d);
+            await d.answer('Start Sourcebot now?', 'y');
+        });
+        assert.equal(result.events.some(e => e.event === 'setup_sourcebot_start_failed'), false);
+        assert.equal(p(result, 'completed').sourcebotStartOutcome, 'spawned');
+    });
+}
+
+test('start failure with unavailable PostHog still exits and retains generated files', async () => {
+    const began = Date.now();
+    const result = await scenario(packed, { telemetry: 'stall', docker: { start: { stderrChunks: ['canary-sensitive-error'] } } }, async d => {
+        await initial(d);
+        await d.answer('Start Sourcebot now?', 'y');
+    });
+    assert.equal(result.exitCode, 0);
+    assert.ok(Date.now() - began < 7000);
+    assert.deepEqual(Object.keys(result.files).sort(), ['.env', 'config.json', 'docker-compose.yml']);
+});
+
 for (const stage of ['fetch', 'docker', 'after_failures']) {
     test(`Ctrl+C during ${stage} cancels outstanding work`, async () => {
         const result = await scenario(packed, {

packages/setupWizard/tests/e2e/fakeDocker.cjs

@@ -4,11 +4,23 @@ fs.appendFileSync(process.env.TEST_DOCKER_LOG, JSON.stringify(args) + '\n');
 const state = JSON.parse(fs.readFileSync(process.env.TEST_DOCKER_STATE, 'utf8'));
 const command = args.slice(0, 2).join(' ');
 fs.appendFileSync(process.env.TEST_DOCKER_PIDS, String(process.pid) + '\n');
-if (state.fail?.includes(command)) {
+if (command === 'compose up' && state.start) {
+    let index = 0;
+    const write = () => {
+        if (index < (state.start.stderrChunks ?? []).length) {
+            process.stderr.write(state.start.stderrChunks[index++]);
+            setTimeout(write, 10);
+        } else if (state.start.signal) {
+            process.kill(process.pid, state.start.signal);
+        } else {
+            process.exit(state.start.exitCode ?? 1);
+        }
+    };
+    setTimeout(write, state.start.delayMs ?? 0);
+} else if (state.fail?.includes(command)) {
     console.error('canary-sensitive-error');
     process.exit(1);
-}
-if (state.stall?.includes(command)) {
+} else if (state.stall?.includes(command)) {
     if (state.descendant) {
         const child = require('node:child_process').spawn(process.execPath, ['-e', "process.on('SIGINT', () => {}); setInterval(() => {}, 1000)"], { stdio: 'ignore' });
         fs.appendFileSync(process.env.TEST_DOCKER_PIDS, String(child.pid) + '\n');

packages/setupWizard/tests/e2e/runtime.test.mjs

@@ -1,13 +1,62 @@
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { writeFileSync, mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { artifact, scenario, minimal } from './harness.mjs';
 import { INSTALL_ID_PATTERN } from '../../dist/telemetry.js';
 
+test('real Docker name conflict emits a private diagnostic after setup completion', async () => {
+    const packed = artifact();
+    const docker = execFileSync('which', ['docker'], { encoding: 'utf8' }).trim();
+    const image = process.env.SETUP_TEST_SOURCEBOT_IMAGE ?? 'docker.sourcebot.dev/sourcebot-dev/sourcebot:latest';
+    const name = `setup-start-conflict-${randomUUID()}`;
+    const project = `setup-start-${randomUUID()}`;
+    let created = false;
+    try {
+        execFileSync(docker, ['create', '--name', name, '--label', `setup-start-test=${project}`, image], { stdio: 'pipe', timeout: 45000 });
+        created = true;
+        const host = execFileSync(docker, ['context', 'inspect', '--format', '{{.Endpoints.docker.Host}}'], { encoding: 'utf8' }).trim();
+        const result = await scenario(packed, {
+            realDocker: docker,
+            compose: `services:\n  sourcebot:\n    image: ${image}\n    container_name: ${name}\n    pull_policy: never\n`,
+            sensitiveValues: [name, project],
+            assertLauncherHome(paths) {
+                // Docker Desktop creates these empty parent directories itself.
+                // Still reject files or any wizard-owned per-user state.
+                const dockerDirectories = process.platform === 'darwin'
+                    ? ['Library', 'Library/Containers', 'Library/Containers/com.docker.docker', 'Library/Containers/com.docker.docker/Data']
+                    : [];
+                assert.deepEqual(paths.filter(path => !dockerDirectories.includes(path)), []);
+            },
+            environment: { COMPOSE_PROJECT_NAME: project, DOCKER_HOST: host, DOCKER_CONFIG: process.env.DOCKER_CONFIG ?? join(homedir(), '.docker') },
+            async cleanupDeployment({ setup }) {
+                execFileSync(docker, ['compose', '-p', project, 'down'], { cwd: setup, stdio: 'pipe', timeout: 45000 });
+            },
+        }, async d => {
+            await minimal(d);
+            await d.answer('Download docker-compose.yml?', 'y');
+            await d.answer('Start Sourcebot now?', 'y');
+            await d.wait('is already in use by container');
+        });
+        const failure = result.events.filter(e => e.event === 'setup_sourcebot_start_failed');
+        assert.equal(failure.length, 1);
+        assert.equal(failure[0].properties.failureReason, 'container_name_conflict');
+        assert.equal(failure[0].properties.failurePhase, 'compose_exit');
+        assert.equal(result.events.at(-1).event, 'setup_sourcebot_start_failed');
+        assert.ok(result.events.some(e => e.event === 'setup_sourcebot_completed'));
+    } finally {
+        try {
+            if (created) execFileSync(docker, ['rm', '-v', name], { stdio: 'pipe', timeout: 45000 });
+        } finally {
+            packed.cleanup();
+        }
+    }
+});
+
 test('real Sourcebot containers: packed wizard identity survives first boot, restart, upgrade and opt-out', async () => {
     const packed = artifact();
     const image = process.env.SETUP_TEST_SOURCEBOT_IMAGE ?? 'docker.sourcebot.dev/sourcebot-dev/sourcebot:latest';