What causes "ExternalDoltConfig: KeepAlivePeriod %s is negative" in gastownhall/beads?

Change KeepAlivePeriod to a positive duration, e.g. "30s".

ExternalDoltConfig: KeepAlivePeriod %s is negative

Error message

ExternalDoltConfig: KeepAlivePeriod %s is negative

What it means

ExternalDoltConfig.Validate rejects a negative KeepAlivePeriod. The value is parsed from a Go time.Duration and is used to configure TCP keep-alives on the connection; a negative duration is meaningless and would cause errors or misbehavior when dialing. The valid range is 0 (disabled/default) or a positive duration.

Source

Thrown at internal/configfile/external_dolt_config.go:98

	if !c.TLSRequired {
		switch {
		case c.TLSCACert != "":
			return errors.New("ExternalDoltConfig: TLSCACert set without TLSRequired")
		case c.TLSCert != "" || c.TLSKey != "":
			return errors.New("ExternalDoltConfig: TLSCert/TLSKey set without TLSRequired")
		case c.TLSServerName != "":
			return errors.New("ExternalDoltConfig: TLSServerName set without TLSRequired")
		case c.TLSSkipVerify:
			return errors.New("ExternalDoltConfig: TLSSkipVerify set without TLSRequired")
		}
	}

	if c.TLSRequired && hasSocket && c.TLSServerName == "" && !c.TLSSkipVerify {
		return errors.New("ExternalDoltConfig: TLSRequired over Socket needs TLSServerName or TLSSkipVerify")
	}

	if c.KeepAlivePeriod < 0 {
		return fmt.Errorf("ExternalDoltConfig: KeepAlivePeriod %s is negative", c.KeepAlivePeriod)
	}

	return nil
}

func (c ExternalDoltConfig) TLSClientConfig() (*tls.Config, error) {
	if !c.TLSRequired {
		return nil, nil
	}

	cfg := &tls.Config{MinVersion: tls.VersionTLS12}

	if c.TLSSkipVerify {
		cfg.InsecureSkipVerify = true //nolint:gosec // G402: opt-in insecure transport via the TLSSkipVerify testing flag
	} else {
		name := c.TLSServerName
		if name == "" {
			name = c.Host

View on GitHub (pinned to 71377f2769)

Solutions

Change KeepAlivePeriod to a positive duration, e.g. "30s".
Set KeepAlivePeriod to 0 to disable explicit keep-alive configuration.
If the value comes from a flag/env, clamp negatives to 0 before constructing the config.

Example fix

// before
keepAlivePeriod: "-30s"
// after
keepAlivePeriod: "30s"

Defensive patterns

Strategy: validation

Validate before calling

func validKeepAlive(cfg configfile.ExternalDoltConfig) error {
    if cfg.KeepAlivePeriod < 0 {
        return fmt.Errorf("KeepAlivePeriod must be >= 0, got %s", cfg.KeepAlivePeriod)
    }
    return nil
}

Prevention

Use time.ParseDuration output directly, never manual strings
Sanitize user/env-supplied durations: if d < 0 { d = 0 }
Use 0 explicitly when you mean "use driver default"

When it happens

Trigger: Calling Validate (via NewExternalDoltServer, NewExternalDoltServerUOWProvider, or buildProxiedServerClientInfo) with KeepAlivePeriod set to a negative duration such as "-5s", "-1m", or a numeric field that was negated.

Common situations: Typo of a leading "-" in a config file; parsing a duration from a signed integer user input; copy-paste of a value with a stray minus sign.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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