gastownhall/beads · info

procid: process-birth identity is not implemented on %s

Error message

procid: process-birth identity is not implemented on %s

What it means

ErrUnsupported is a sentinel error (public var) indicating that process-birth identity (PID + start-time tokens, the anti-PID-reuse mechanism) has no implementation on the current OS (runtime.GOOS is baked into the message). It is returned by Capture (and Open) on unsupported platforms so dbproxy-dependent callers refuse cleanly at startup instead of operating with an unverifiable PID. Ordinary bd usage outside dbproxy is unaffected by design.

Source

Thrown at internal/procid/procid_unsupported.go:19

//go:build !linux && !darwin && !windows

package procid

import (
	"fmt"
	"os"
	"runtime"
)

// ErrUnsupported marks platforms with no process-birth identity
// implementation (no /proc, no pidfd, no SysctlKinfoProc in x/sys). The
// dbproxy machinery that needs birth identity refuses cleanly at startup
// there instead of running with an unverifiable PID: reattach-and-signal
// without birth identity is exactly the PID-reuse race this package exists
// to close. Everything outside dbproxy is independent of procid, so ordinary
// bd use on these platforms is unaffected — which matches what they had
// before dbproxy existed (v1.1.2 shipped FreeBSD with no dbproxy at all).
var ErrUnsupported = fmt.Errorf("procid: process-birth identity is not implemented on %s", runtime.GOOS)

// Handle exists so cross-platform callers type-check; no instance can be
// constructed because Open always fails.
type Handle struct{}

func Capture(pid int) (Token, error) { return "", ErrUnsupported }

func Verify(pid int, tok Token) (bool, error) { return false, ErrUnsupported }

func Open(pid int, tok Token) (*Handle, error) { return nil, ErrUnsupported }

func (h *Handle) Signal(sig os.Signal) error { return ErrUnsupported }

func (h *Handle) Kill() error { return ErrUnsupported }

func (h *Handle) Close() error { return nil }

// IsProcessGone reports false: ErrUnsupported is a capability statement, not

View on GitHub (pinned to 71377f2769)

Solutions

1. If you do not need process-birth identity, keep usage outside dbproxy — ordinary bd commands work fine on these platforms
2. On FreeBSD and similar, either avoid enabling dbproxy machinery or run the dbproxy-dependent component on Linux/Windows instead
3. If you need support on a new platform, implement a procid_<goos>.go backend providing Capture/Verify with platform birth identity (e.g. kvm/proc credentials on BSDs)
4. Check errors.Is(err, procid.ErrUnsupported) at startup to fail fast with a clear message instead of a mid-run surprise

Example fix

// before
tok, err := procid.Capture(pid)
if err != nil {
	return err // cryptic "not implemented on freebsd" mid-flight
}
// after
tok, err := procid.Capture(pid)
if errors.Is(err, procid.ErrUnsupported) {
	return fmt.Errorf("dbproxy requires birth identity; unsupported on %s — run on linux/windows", runtime.GOOS)
}
if err != nil {
	return err
}

func birthIdentitySupported() bool {
	switch runtime.GOOS {
	case "linux", "windows":
		return true
	default:
		return false
	}
}

func isUnsupportedPlatform(err error) bool {
	return errors.Is(err, procid.ErrUnsupported)
}

tok, err := procid.Capture(pid)
if errors.Is(err, procid.ErrUnsupported) {
	// degrade: skip identity verification or refuse dbproxy features
	log.Warnf("no birth identity on %s; skipping PID-reuse protection", runtime.GOOS)
	return runWithoutIdentity(pid)
}
if err != nil {
	return err
}

When it happens

Trigger: Calling procid.Capture, procid.Open, or any Handle-using API (e.g. inside dbproxy startup) on FreeBSD, OpenBSD, NetBSD, or any GOOS without a procid implementation file (only Linux and Windows have real implementations); building/running dbproxy-dependent machinery on such a platform.

Common situations: Deploying beads with dbproxy enabled to FreeBSD after v1.1.2 (which shipped FreeBSD with no dbproxy at all); cross-compiling and running on a BSD variant; CI matrix jobs on unsupported GOOS.

Related errors

• lock already held by another process
• procid: process %d no longer matches token
• procid: process %d does not match token
• procid: process %d does not match token
• procid: process no longer matches token

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