{"record":{"id":"22a972961d02a4c4","repo":"gastownhall/beads","slug":"pidfile-invalid-pid","errorCode":null,"errorMessage":"pidfile: invalid pid","messagePattern":"pidfile: invalid pid","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/pidfile/pidfile.go","lineNumber":33,"sourceCode":"\tPort        int    `json:\"port\"`\n\tUpstreamID  string `json:\"upstream_id,omitempty\"`\n\tSchema      int    `json:\"schema,omitempty\"`\n\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","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/pidfile/pidfile.go#L15-L51","documentation":"ErrBadPid means a pidfile contains a PID value that is invalid (missing, non-numeric, or otherwise unusable) for liveness checks and signaling. ValidateV2 and TestValidateV2 reject such pidfiles so callers never signal an unvalidated PID.","triggerScenarios":"ValidateV2 or TestValidateV2 called on a PidFile whose PID field fails validation; readAndDial/stopAndAcquire reading a corrupted or hand-edited pidfile.","commonSituations":"Truncated or corrupted pidfile after a crash; manual edits to the JSON; a partially written pidfile from an interrupted process start.","solutions":["Delete the corrupted pidfile and restart the proxy to regenerate it","Re-run the proxy start command so stopAndAcquire rewrites the pidfile atomically","Check errors.Is(err, pidfile.ErrBadPid) and quarantine the record instead of attempting to signal the PID"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var pf pidfile.PidFile\njson.Unmarshal(data, &pf)\nif pf.PID <= 0 { return fmt.Errorf(\"pidfile %s has invalid pid\", path) }","typeGuard":"func isBadPid(err error) bool { return errors.Is(err, pidfile.ErrBadPid) }","tryCatchPattern":"if err := pf.ValidateV2(kind); err != nil {\n    if errors.Is(err, pidfile.ErrBadPid) { os.Remove(path) }\n    return err\n}","preventionTips":["Never manually edit pidfiles","Delete pidfiles after abnormal shutdowns","Verify process.Start completes before reading pidfiles"],"tags":["pidfile","process","corruption"],"backgroundTag":"invalid-pid","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}