gastownhall/beads · error

pidfile: invalid pid

Error message

pidfile: invalid pid

What it means

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.

Source

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

	Port        int    `json:"port"`
	UpstreamID  string `json:"upstream_id,omitempty"`
	Schema      int    `json:"schema,omitempty"`
	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

View on GitHub (pinned to 71377f2769)

Solutions

1. Delete the corrupted pidfile and restart the proxy to regenerate it
2. Re-run the proxy start command so stopAndAcquire rewrites the pidfile atomically
3. Check errors.Is(err, pidfile.ErrBadPid) and quarantine the record instead of attempting to signal the PID

var pf pidfile.PidFile
json.Unmarshal(data, &pf)
if pf.PID <= 0 { return fmt.Errorf("pidfile %s has invalid pid", path) }

func isBadPid(err error) bool { return errors.Is(err, pidfile.ErrBadPid) }

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

When it happens

Trigger: ValidateV2 or TestValidateV2 called on a PidFile whose PID field fails validation; readAndDial/stopAndAcquire reading a corrupted or hand-edited pidfile.

Common situations: Truncated or corrupted pidfile after a crash; manual edits to the JSON; a partially written pidfile from an interrupted process start.

Related errors

• verify proxy spawn owner pid %d: %w
• pidfile: legacy schema
• pidfile: invalid port
• ErrKindMismatch
• ErrMissingBirth

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