{"record":{"id":"d0fe90145a4c12b0","repo":"gastownhall/beads","slug":"pidfile-invalid-port","errorCode":null,"errorMessage":"pidfile: invalid port","messagePattern":"pidfile: invalid port","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/storage/dbproxy/pidfile/pidfile.go","lineNumber":34,"sourceCode":"\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\n\t}","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/storage/dbproxy/pidfile/pidfile.go#L16-L52","documentation":"ErrBadPort means the pidfile's port field is invalid or missing, so the proxy endpoint cannot be dialed. ValidateV2/TestValidateV2 reject pidfiles without a usable port to prevent dialing garbage values.","triggerScenarios":"ValidateV2 or TestValidateV2 on a PidFile with a missing/invalid Port or ControlPort; reading a pidfile written by a buggy or interrupted writer.","commonSituations":"Disk corruption or partial writes; hand-editing the pidfile; version skew where a v1 writer omitted fields the v2 validator requires.","solutions":["Remove the bad pidfile and restart the proxy so a correct one is published","Recreate the workspace proxy (the managed child re-binds and publishes a fresh port)","Check errors.Is(err, pidfile.ErrBadPort) and treat the endpoint as dead rather than dialing"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var pf pidfile.PidFile\njson.Unmarshal(data, &pf)\nif pf.Port <= 0 || pf.Port > 65535 { return fmt.Errorf(\"pidfile %s bad port\", path) }","typeGuard":"func isBadPort(err error) bool { return errors.Is(err, pidfile.ErrBadPort) }","tryCatchPattern":"if err := pf.ValidateV2(kind); err != nil {\n    if errors.Is(err, pidfile.ErrBadPort) { os.Remove(path) }\n    return err\n}","preventionTips":["Let the library publish ports atomically","Do not share pidfile paths between components","Regenerate pidfiles rather than patching them"],"tags":["pidfile","port","validation"],"backgroundTag":"invalid-port-config","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}