gastownhall/beads · error

ExternalDoltConfig: Socket

Error message

ExternalDoltConfig: Socket %q is not absolute

What it means

ExternalDoltConfig.Validate rejects a Socket path that is not an absolute filesystem path. The external Dolt server connection uses unix domain sockets, which the Go MySQL driver can only dial via an absolute path; a relative path would resolve unpredictably depending on the process working directory. Validate is invoked when constructing the external Dolt server client, so this fails fast at configuration load time.

Solutions

1. Set Socket to an absolute path, e.g. "/run/dolt/dolt.sock" or an expanded "$HOME/.dolt/dolt.sock".
2. In a shell-launched config, expand variables before use: use $(echo $HOME)/.dolt/dolt.sock or the expanded literal path.
3. If you meant a TCP connection, remove Socket and set Host/Port instead.

Example fix

// before
socket: "dolt.sock"
// after
socket: "/run/user/1000/dolt/dolt.sock"

func validSocket(cfg configfile.ExternalDoltConfig) error {
    if cfg.Socket != "" && !filepath.IsAbs(cfg.Socket) {
        abs, err := filepath.Abs(cfg.Socket)
        if err != nil {
            return err
        }
        cfg.Socket = abs
    }
    return nil
}

When it happens

Trigger: Calling NewExternalDoltServer, NewExternalDoltServerUOWProvider, or buildProxiedServerClientInfo with ExternalDoltConfig.Socket set to a relative path (e.g. "dolt.sock" or "./run/dolt.sock") while Host is unset. Any config file or env-derived value like "$HOME/..." left unexpanded also triggers it.

Common situations: Hand-writing a config with a relative socket path; using an environment variable (e.g. $DOLT_SOCKET) that is empty or relative; copying a config between machines where the socket lives in a different absolute location.

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

• ExternalDoltConfig: TLSCACert
• ExternalDoltConfig: TLSCert
• ExternalDoltConfig: TLSKey
• agents file must be a simple filename without path…
• agents file must have .md extension, got

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

Appendix: source

Thrown at internal/configfile/external_dolt_config.go:60

	hasSocket := c.Socket != ""

	switch {
	case hasSocket && (hasHost || hasPort):
		return errors.New("ExternalDoltConfig: set either Socket OR (Host, Port), not both")
	case !hasSocket && !hasHost && !hasPort:
		return errors.New("ExternalDoltConfig: must set Socket or (Host, Port)")
	case hasHost && !hasPort:
		return errors.New("ExternalDoltConfig: Host requires Port")
	case !hasHost && hasPort:
		return errors.New("ExternalDoltConfig: Port requires Host")
	}

	if hasHost && (c.Port < 1 || c.Port > 65535) {
		return fmt.Errorf("ExternalDoltConfig: Port %d out of range [1, 65535]", c.Port)
	}

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

View on GitHub (pinned to 71377f2769)