What causes "ExternalDoltConfig: TLSCACert %q is not absolute" in gastownhall/beads?

Set TLSCACert to an absolute path, e.g. "/etc/beads/tls/ca.pem".

ExternalDoltConfig: TLSCACert %q is not absolute

Error message

ExternalDoltConfig: TLSCACert %q is not absolute

What it means

ExternalDoltConfig.Validate requires TLSCACert to be an absolute path when set. The CA bundle is read with os.ReadFile in TLSClientConfig to build the root cert pool; a relative path would depend on the working directory. Validation rejects it early, at config load/construction time.

Source

Thrown at internal/configfile/external_dolt_config.go:77

	if hasSocket && !filepath.IsAbs(c.Socket) {
		return fmt.Errorf("ExternalDoltConfig: Socket %q is not absolute", c.Socket)
	}

	switch {
	case c.TLSCert != "" && c.TLSKey == "":
		return errors.New("ExternalDoltConfig: TLSCert set without TLSKey")
	case c.TLSCert == "" && c.TLSKey != "":
		return errors.New("ExternalDoltConfig: TLSKey set without TLSCert")
	}

	if c.TLSCert != "" && !filepath.IsAbs(c.TLSCert) {
		return fmt.Errorf("ExternalDoltConfig: TLSCert %q is not absolute", c.TLSCert)
	}
	if c.TLSKey != "" && !filepath.IsAbs(c.TLSKey) {
		return fmt.Errorf("ExternalDoltConfig: TLSKey %q is not absolute", c.TLSKey)
	}
	if c.TLSCACert != "" && !filepath.IsAbs(c.TLSCACert) {
		return fmt.Errorf("ExternalDoltConfig: TLSCACert %q is not absolute", c.TLSCACert)
	}

	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")
	}

View on GitHub (pinned to 71377f2769)

Solutions

Set TLSCACert to an absolute path, e.g. "/etc/beads/tls/ca.pem".
Expand "~/" or environment variables in the value before saving config.
If the server uses a CA already in the system pool, remove TLSCACert.

Example fix

// before
tlsCACert: "./ca.pem"
// after
tlsCACert: "/usr/local/share/ca-certificates/dolt-ca.pem"

Defensive patterns

Strategy: validation

Validate before calling

func validTLSCACert(cfg configfile.ExternalDoltConfig) error {
    if cfg.TLSCACert != "" && !filepath.IsAbs(cfg.TLSCACert) {
        return fmt.Errorf("TLSCACert must be absolute: %q", cfg.TLSCACert)
    }
    return nil
}

Prevention

Install custom CAs under a fixed absolute directory
Validate config at startup with a linter that checks path absoluteness
Rely on the system cert pool instead of TLSCACert when possible

When it happens

Trigger: Calling Validate (via NewExternalDoltServer, NewExternalDoltServerUOWProvider, or buildProxiedServerClientInfo) with TLSCACert set to a relative path like "ca.pem" or "~/ca.pem" (tilde is not absolute to Go).

Common situations: Custom CA deployed to a nonstandard location referenced relatively; config templating that did not expand variables; moving configs between dev laptops and servers.

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/3302b7cd6a178d26. Report an issue: GitHub.