{"record":{"id":"73674c466c5cc2c1","repo":"gastownhall/beads","slug":"errmissingbirth","errorCode":"ErrMissingBirth","errorMessage":"pidfile: missing birth token","messagePattern":"pidfile: missing birth token","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/pidfile/pidfile.go","lineNumber":36,"sourceCode":"\tKind        string `json:\"kind,omitempty\"`\n\tBirth       string `json:\"birth,omitempty\"`\n\tRootID      string `json:\"root_id,omitempty\"`\n\tControlPort int    `json:\"control_port,omitempty\"`\n}\n\nconst SchemaV2 = 2\n\nconst (\n\tKindProxy       = \"db-proxy\"\n\tKindDoltBackend = \"dolt-backend\"\n)\n\nvar (\n\tErrLegacySchema = errors.New(\"pidfile: legacy schema\")\n\tErrBadPid       = errors.New(\"pidfile: invalid pid\")\n\tErrBadPort      = errors.New(\"pidfile: invalid port\")\n\tErrKindMismatch = errors.New(\"pidfile: kind mismatch\")\n\tErrMissingBirth = errors.New(\"pidfile: missing birth token\")\n)\n\n// ValidateV2 validates the fields required for a schema v2 pidfile.\nfunc (p *PidFile) ValidateV2(wantKind string) error {\n\tif p.Schema < SchemaV2 {\n\t\treturn ErrLegacySchema\n\t}\n\tif p.Pid <= 0 {\n\t\treturn ErrBadPid\n\t}\n\tif p.Port < 1 || p.Port > 65535 || (p.ControlPort != 0 && (p.ControlPort < 1 || p.ControlPort > 65535)) {\n\t\treturn ErrBadPort\n\t}\n\tif p.Kind != wantKind {\n\t\treturn ErrKindMismatch\n\t}\n\tif p.Birth == \"\" {\n\t\treturn ErrMissingBirth","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/pidfile/pidfile.go#L18-L54","documentation":"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.","triggerScenarios":"ValidateV2 or TestValidateV2 on a PidFile whose Birth field is empty; a v2-schema pidfile written by code that skipped birth-token generation.","commonSituations":"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.","solutions":["Delete the incomplete pidfile and restart the proxy so a full v2 record with a birth token is written","Regenerate the pidfile via the normal start/stopAndAcquire path rather than editing it by hand","Check errors.Is(err, pidfile.ErrMissingBirth) and quarantine the unverifiable record"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var pf pidfile.PidFile\njson.Unmarshal(data, &pf)\nif pf.Birth == \"\" { return fmt.Errorf(\"pidfile %s missing birth token\", path) }","typeGuard":"func isMissingBirth(err error) bool { return errors.Is(err, pidfile.ErrMissingBirth) }","tryCatchPattern":"if err := pf.ValidateV2(kind); err != nil {\n    if errors.Is(err, pidfile.ErrMissingBirth) { os.Remove(path) }\n    return err\n}","preventionTips":["Always create pidfiles through the library's writer","Do not strip fields in migration tooling","Regenerate pidfiles after crash recovery"],"tags":["pidfile","security","identity"],"backgroundTag":"missing-birth-token","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}