gastownhall/beads · error

ExternalDoltConfig: Port %d out of range [1, 65535]

Error message

ExternalDoltConfig: Port %d out of range [1, 65535]

What it means

ExternalDoltConfig.Validate() checks the external dolt sql-server connection settings. When Host is set, Port must also be set and lie within [1, 65535]; a host with an out-of-range port (negative, zero handled earlier, or >65535) fails validation with this message before any connection attempt.

Source

Thrown at internal/configfile/external_dolt_config.go:56

func (c ExternalDoltConfig) Validate() error {
	hasHost := c.Host != ""
	hasPort := c.Port != 0
	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)

View on GitHub (pinned to 71377f2769)

Solutions

1. Set Port to a valid TCP port 1-65535 (default Dolt server port is 3307)
2. Check the port value in metadata.json (dolt_server_port) and any BEADS_* env override for typos
3. If the port is parsed from a string, validate with strconv.Atoi and range-check before assigning
4. If you only have a host and no port, either add the correct port or switch to Socket-only configuration

Example fix

// before
cfg := configfile.ExternalDoltConfig{Host: "dolt.internal", Port: 99999}
// after
cfg := configfile.ExternalDoltConfig{Host: "dolt.internal", Port: 3307}
if err := cfg.Validate(); err != nil { return err }

func validPort(p int) bool { return p >= 1 && p <= 65535 }
// before building ExternalDoltConfig:
if host != "" && !validPort(port) {
	return fmt.Errorf("port %d out of range for host %s", port, host)
}

func hasValidHostPort(c configfile.ExternalDoltConfig) bool {
	return c.Host != "" && c.Port >= 1 && c.Port <= 65535
}

cfg := configfile.ExternalDoltConfig{Host: host, Port: port}
if err := cfg.Validate(); err != nil {
	if strings.Contains(err.Error(), "out of range") {
		return fmt.Errorf("fix dolt_server_port in metadata.json/env: %w", err)
	}
	return err
}

When it happens

Trigger: Constructing ExternalDoltConfig or calling NewExternalDoltServer / NewExternalDoltServerUOWProvider / buildProxiedServerClientInfo with Host non-empty and Port < 1 or > 65535 — e.g. Port parsed from a bad env var, a config typo like 655360, or int overflow from an unparsed string (Port defaulting to a sentinel like -1).

Common situations: Typo in dolt_server_port in metadata.json or a BEADS_* env var; pasting an HTTPS URL port (e.g. 44300 typo); leaving a -1 placeholder; copy-pasting a port above 65535.

Related errors

• database name cannot be empty
• uow: doltBinExec must not be empty
• uow: get proxy endpoint: %w
• uow: database name must not be empty (caller should default
• uow: rootUser must not be empty

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