t8y2/dbx · error

Neo4j host is required

Error message

Neo4j host is required

What it means

buildNeo4jURI assembles the neo4j:// (or neo4j+s://) connection URI from the params. When no pre-parsed URI was supplied and params.Host is empty or whitespace-only, there is no host to build a URI from, so it fails fast with this error.

Source

Thrown at agents/drivers/neo4j-go/driver.go:127

		}
	}, nil
}

func buildNeo4jURI(params connectParams) (string, error) {
	if value := strings.TrimSpace(params.ConnectionString); value != "" {
		value = strings.TrimPrefix(value, "jdbc:")
		parsed, err := url.Parse(value)
		if err == nil && isNeo4jScheme(parsed.Scheme) && parsed.Host != "" {
			parsed.User = nil
			parsed.Path = ""
			parsed.RawPath = ""
			parsed.RawQuery = filterDriverURIQuery(parsed.Query()).Encode()
			return parsed.String(), nil
		}
	}
	host := strings.TrimSpace(params.Host)
	if host == "" {
		return "", errors.New("Neo4j host is required")
	}
	port := params.Port
	if port <= 0 {
		port = defaultNeo4jPort
	}
	scheme := "neo4j"
	query := parseURLParams(params.URLParams)
	if configured := strings.ToLower(strings.TrimSpace(query.Get("scheme"))); isNeo4jScheme(configured) {
		scheme = configured
	} else if params.SSL || queryBool(query, "ssl") || queryBool(query, "encrypted") || params.CACertPath != "" || params.ClientCertPath != "" {
		scheme = "neo4j+s"
	}
	return (&url.URL{Scheme: scheme, Host: net.JoinHostPort(host, strconv.Itoa(port))}).String(), nil
}

func isNeo4jScheme(value string) bool {
	switch strings.ToLower(value) {
	case "neo4j", "neo4j+s", "neo4j+ssc", "bolt", "bolt+s", "bolt+ssc":

View on GitHub (pinned to c0390bff16)

Solutions

1. Set params.Host to the Neo4j server hostname or IP.
2. Alternatively pass a full connection URI (e.g. neo4j+s://host:7687) instead of host/port fields.
3. Check the env/config source that populates Host; log the params struct to confirm it is not empty.

Example fix

// before
params := neo4jgo.DriverParams{Port: 7687} // Host empty
// after
params := neo4jgo.DriverParams{Host: "neo4j.internal", Port: 7687}

if uri == "" && strings.TrimSpace(host) == "" {
    return errors.New("neo4j: either uri or host must be configured")
}

When it happens

Trigger: Calling openDriver (directly or via the driver agent's open/connect dispatch) with neither a URI nor params.Host, or with params.Host set to " " (whitespace only, trimmed away).

Common situations: Env var for the Neo4j host not set in a deployment, config struct zero-valued because YAML/JSON keys mismatched, forgetting host when only port/credentials were configured.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• H2 JDBC driver rejected URL: " + buildJdbcUrl(params)
• Hive host is required
• both client certificate and client key are required
• not connected
• cannot reconnect Xugu session without connection parameters

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/8ac87a8ed83d41f5. Report an issue: GitHub.