t8y2/dbx · error

Cassandra host is required

Error message

Cassandra host is required

What it means

parseCassandraConfig rejects the final config when no hosts were configured and no secure-connect-bundle was provided: there is no way to know which Cassandra cluster to contact. finalize() has already passed, so the config is internally valid but has no connection target.

Source

Thrown at agents/drivers/cassandra-go/config.go:103

	if err != nil {
		return cassandraConfig{}, err
	}
	for key, values := range urlParams {
		params[key] = values
	}
	if err := applyCassandraURLParams(&config, params); err != nil {
		return cassandraConfig{}, err
	}
	if config.configFile != "" {
		if err := applyCassandraConfigFile(&config, config.configFile); err != nil {
			return cassandraConfig{}, err
		}
	}
	if err := config.finalize(); err != nil {
		return cassandraConfig{}, err
	}
	if len(config.hosts) == 0 && config.secureConnectBundle == "" {
		return cassandraConfig{}, fmt.Errorf("Cassandra host is required")
	}
	if len(config.hosts) > 0 && !config.disableInitialHostLookup && allLoopbackHosts(config.hosts) {
		config.disableInitialHostLookup = true
	}
	return config, nil
}

func applyConnectionString(config *cassandraConfig, params url.Values, raw string) error {
	value := strings.TrimSpace(raw)
	value = strings.TrimPrefix(value, "jdbc:")
	if !strings.Contains(value, "://") {
		return fmt.Errorf("unsupported Cassandra connection string: %s", raw)
	}
	parsed, err := url.Parse(value)
	if err != nil {
		return fmt.Errorf("invalid Cassandra connection string: %w", err)
	}
	if parsed.Scheme != "cassandra" {

View on GitHub (pinned to c0390bff16)

Solutions

  1. Add the host(s): set the host/hosts parameter or include host:port in the connection URL.
  2. For Astra/DataStax, supply the secure-connect-bundle parameter pointing to the downloaded zip.
  3. Check spelling of config keys and that the config file was actually found (missing files are ignored for JDBC compatibility).
  4. Verify env vars feeding the config are non-empty at runtime.

Example fix

// before
cfg := map[string]string{"keyspace": "sales"} // no host, no bundle
// after
cfg := map[string]string{"host": "10.0.0.5,10.0.0.6", "keyspace": "sales"}
// or: cfg["secure-connect-bundle"] = "/path/to/secure-connect.zip"
Defensive patterns

Strategy: validation

Validate before calling

hosts := cfg.Hosts
bundle := cfg.SecureConnectBundle
if len(hosts) == 0 && bundle == "" {
    return fmt.Errorf("cassandra config requires hosts or secure-connect-bundle before opening")
}

Try / catch

c, err := connector.Open(dsn)
if err != nil && strings.Contains(err.Error(), "Cassandra host is required") {
    return nil, fmt.Errorf("no connection target: set host/hosts or secure-connect-bundle (check key spelling and env vars): %w", err)
}

Prevention

When it happens

Trigger: Calling parseCassandraConfig (via driver open/config parsing) with an empty hosts list, no 'host'/'hosts' JDBC-style parameter, no URL host portion, and no secure-connect-bundle parameter or file-derived bundle path.

Common situations: Migrating from a JDBC string and forgetting the host; Astra users removing the host but not supplying the secure connect bundle; config file parsed but keys misspelled (e.g. 'hostname' instead of 'host'); environment-driven config where the env var is empty.

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

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