gastownhall/beads · error

capture proxy birth identity: %w

Error message

capture proxy birth identity: %w

What it means

Wraps a failure of procid.Capture(os.Getpid()), which snapshots the proxy process's birth identity (e.g. start time + pid used to safely identify the process later). If this OS-level capture fails, ListenAndServe tears down the backend and aborts startup, because publishing a pidfile without a verified birth identity would be unsafe for later ownership checks.

Source

Thrown at internal/storage/dbproxy/proxy/server.go:282

		if changed, cerr := stopEpochChanged(p.rootDir, p.stopEpoch); cerr == nil && changed {
			return fmt.Errorf("%w for %s: stop epoch advanced during backend start (%v)", errStartInterrupted, p.rootDir, err)
		}
		return fmt.Errorf("start database server: %w", err)
	}

	if err := waitForServerReady(ctx, p.server, serverReadyTimeout); err != nil {
		if changed, cerr := stopEpochChanged(p.rootDir, p.stopEpoch); cerr == nil && changed {
			return abortInterruptedStart()
		}
		p.stats.IncBackendStop()
		_ = stopBackendBounded(p.server)
		return fmt.Errorf("database server not ready: %w", err)
	}
	birth, err := procid.Capture(os.Getpid())
	if err != nil {
		p.stats.IncBackendStop()
		_ = stopBackendBounded(p.server)
		return fmt.Errorf("capture proxy birth identity: %w", err)
	}
	rootID, err := identity.RootID(p.rootDir)
	if err != nil {
		p.stats.IncBackendStop()
		_ = stopBackendBounded(p.server)
		return fmt.Errorf("resolve proxy root identity: %w", err)
	}
	upstreamID := p.server.ID(ctx)
	identMu.Lock()
	identReply.RootID = rootID
	identReply.UpstreamID = upstreamID
	identReply.PID = os.Getpid()
	identReply.Birth = string(birth)
	identReply.ControlPort = control.Port()
	identMu.Unlock()

	// Last fence before publishing: the spawn marker was cleared when this
	// process took proxy.lock, so a `bd dolt stop` that began during a slow

View on GitHub (pinned to 71377f2769)

Solutions

1. Ensure /proc is mounted and readable for the proxy process inside the container
2. Review seccomp/AppArmor policies blocking procfs reads and allowlist them
3. Upgrade to a release supporting the current platform if the OS lacks the required metadata file
4. Check that the process was not already reaped/modified concurrently (very rare)

// Verify procfs is readable before starting (Linux)
if _, err := os.Stat("/proc/self/stat"); err != nil {
    log.Fatalf("procfs unavailable, procid.Capture will fail: %v", err)
}

if err := p.ListenAndServe(ctx); err != nil {
    if strings.Contains(err.Error(), "capture proxy birth identity") {
        log.Fatalf("process identity capture unsupported in this environment: %v", err)
    }
    log.Fatal(err)
}

When it happens

Trigger: procid.Capture fails, typically when the OS mechanism used to read process start metadata (e.g. /proc/<pid>/stat on Linux) is unavailable or unreadable in the container/sandbox.

Common situations: Minimal containers without /proc mounted (or mounted with hidepid); hardened seccomp profiles blocking the required syscalls; exotic platforms where the procid implementation is unsupported.

Related errors

• ErrUnverifiableProcess
• capture spawning process identity: %w
• empty executable basename for pid %d
• procid: malformed proc stat: missing comm terminator
• procid: malformed proc stat: missing starttime

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/91f69bf919b4e5e1. Report an issue: GitHub.