jackc/pgx · error

failed to split host:port in

Error message

failed to split host:port in '%s', err: %w

What it means

A host entry in the connection URL's host list could not be parsed into host and port components by net.SplitHostPort. The %s shows the offending host string. This is a malformed connection URL.

Solutions

1. Check the connection URL host formatting; ensure ports are separated by colons
2. Verify IPv6 addresses are enclosed in brackets, e.g. [::1]:5432
3. Remove stray characters or extra colons from the host list
4. Test each host entry individually

When it happens

Trigger: Thrown at pgconn/config.go:683 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /api/errors/3cae17036939d70d. Report an issue: GitHub.

Appendix: source

Thrown at pgconn/config.go:683

		if password, present := parsedURL.User.Password(); present {
			settings["password"] = password
		}
	}

	// Handle multiple host:port's in url.Host by splitting them into host,host,host and port,port,port.
	var hosts []string
	var ports []string
	for host := range strings.SplitSeq(parsedURL.Host, ",") {
		if host == "" {
			continue
		}
		if isIPOnly(host) {
			hosts = append(hosts, strings.Trim(host, "[]"))
			continue
		}
		h, p, err := net.SplitHostPort(host)
		if err != nil {
			return nil, fmt.Errorf("failed to split host:port in '%s', err: %w", host, err)
		}
		if h != "" {
			hosts = append(hosts, h)
		}
		if p != "" {
			ports = append(ports, p)
		}
	}
	if len(hosts) > 0 {
		settings["host"] = strings.Join(hosts, ",")
	}
	if len(ports) > 0 {
		settings["port"] = strings.Join(ports, ",")
	}

	database := strings.TrimLeft(parsedURL.Path, "/")
	if database != "" {
		settings["database"] = database

View on GitHub (pinned to ec1a0befd2)