gastownhall/beads · error

ErrMissingBirth

ErrMissingBirth

Error message

pidfile: missing birth token

What it means

ErrMissingBirth means a schema-v2 pidfile lacks the required birth token — the random identifier that ties a running process to its pidfile for workspace-scoped identity verification. Without it the library cannot distinguish the current process from a recycled-PID impostor, so validation fails.

Source

Thrown at internal/storage/dbproxy/pidfile/pidfile.go:36

	Kind        string `json:"kind,omitempty"`
	Birth       string `json:"birth,omitempty"`
	RootID      string `json:"root_id,omitempty"`
	ControlPort int    `json:"control_port,omitempty"`
}

const SchemaV2 = 2

const (
	KindProxy       = "db-proxy"
	KindDoltBackend = "dolt-backend"
)

var (
	ErrLegacySchema = errors.New("pidfile: legacy schema")
	ErrBadPid       = errors.New("pidfile: invalid pid")
	ErrBadPort      = errors.New("pidfile: invalid port")
	ErrKindMismatch = errors.New("pidfile: kind mismatch")
	ErrMissingBirth = errors.New("pidfile: missing birth token")
)

// ValidateV2 validates the fields required for a schema v2 pidfile.
func (p *PidFile) ValidateV2(wantKind string) error {
	if p.Schema < SchemaV2 {
		return ErrLegacySchema
	}
	if p.Pid <= 0 {
		return ErrBadPid
	}
	if p.Port < 1 || p.Port > 65535 || (p.ControlPort != 0 && (p.ControlPort < 1 || p.ControlPort > 65535)) {
		return ErrBadPort
	}
	if p.Kind != wantKind {
		return ErrKindMismatch
	}
	if p.Birth == "" {
		return ErrMissingBirth

View on GitHub (pinned to 71377f2769)

Solutions

1. Delete the incomplete pidfile and restart the proxy so a full v2 record with a birth token is written
2. Regenerate the pidfile via the normal start/stopAndAcquire path rather than editing it by hand
3. Check errors.Is(err, pidfile.ErrMissingBirth) and quarantine the unverifiable record

var pf pidfile.PidFile
json.Unmarshal(data, &pf)
if pf.Birth == "" { return fmt.Errorf("pidfile %s missing birth token", path) }

func isMissingBirth(err error) bool { return errors.Is(err, pidfile.ErrMissingBirth) }

if err := pf.ValidateV2(kind); err != nil {
    if errors.Is(err, pidfile.ErrMissingBirth) { os.Remove(path) }
    return err
}

When it happens

Trigger: ValidateV2 or TestValidateV2 on a PidFile whose Birth field is empty; a v2-schema pidfile written by code that skipped birth-token generation.

Common situations: Partially written or hand-trimmed pidfile JSON; migration tooling stripping fields; a proxy from a build predating birth tokens writing a schema it should not.

Related errors

• authenticated proxy identity does not match its pidfile or w
• identity: oversized reply
• identity: invalid reply MAC
• identity: reply authentication failed
• --allowed-host is empty; pass the Host header value clients

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