gastownhall/beads · error

pidfile: invalid port

Error message

pidfile: invalid port

What it means

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.

Source

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

	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. Remove the bad pidfile and restart the proxy so a correct one is published
2. Recreate the workspace proxy (the managed child re-binds and publishes a fresh port)
3. Check errors.Is(err, pidfile.ErrBadPort) and treat the endpoint as dead rather than dialing

var pf pidfile.PidFile
json.Unmarshal(data, &pf)
if pf.Port <= 0 || pf.Port > 65535 { return fmt.Errorf("pidfile %s bad port", path) }

func isBadPort(err error) bool { return errors.Is(err, pidfile.ErrBadPort) }

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

When it happens

Trigger: ValidateV2 or TestValidateV2 on a PidFile with a missing/invalid Port or ControlPort; reading a pidfile written by a buggy or interrupted writer.

Common situations: Disk corruption or partial writes; hand-editing the pidfile; version skew where a v1 writer omitted fields the v2 validator requires.

Related errors

• record has no valid pid
• --server-port must be between 1 and 65535, got %d; omit the
• ExternalDoltConfig: Port %d out of range [1, 65535]
• proxy.ForceStopUnverified: record %s has invalid pid %d
• no store is open for this workspace

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