t8y2/dbx · error

unsupported Cassandra URL parameter: %s

Error message

unsupported Cassandra URL parameter: %s

What it means

Any URL parameter not recognized by applyCassandraURLParams's switch is rejected with this error, listing the raw key. The native agent supports a fixed subset of the Java/JDBC driver options, so unknown parameters fail fast instead of being silently ignored.

Source

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

		case "kerberosusekeytab", "usekeytab":
			enabled, err := strconv.ParseBool(value)
			if err != nil {
				return fmt.Errorf("invalid usekeytab option: %w", err)
			}
			config.kerberos.useKeytab = enabled
			config.kerberos.useKeytabSet = true
		case "kerberosuseticketcache", "useticketcache":
			enabled, err := strconv.ParseBool(value)
			if err != nil {
				return fmt.Errorf("invalid useticketcache option: %w", err)
			}
			config.kerberos.useTicketCache = enabled
			config.kerberos.useTicketCacheSet = true
		case "compliancemode":
			// JDBC compliance modes only alter java.sql behavior. The native DBX
			// JSON-RPC contract already defines statement and transaction behavior.
		default:
			return fmt.Errorf("unsupported Cassandra URL parameter: %s", rawKey)
		}
	}
	return nil
}

func (config cassandraConfig) clusterConfig(keyspace string) (*gocql.ClusterConfig, error) {
	var cluster *gocql.ClusterConfig
	var err error
	if config.secureConnectBundle != "" {
		cluster, err = gocqlastra.NewClusterFromBundle(
			config.secureConnectBundle,
			config.username,
			config.password,
			config.connectTimeout,
		)
		if err != nil {
			return nil, fmt.Errorf("load Cassandra secure connect bundle: %w", err)
		}

View on GitHub (pinned to c0390bff16)

Solutions

1. Remove the unsupported parameter from the URL
2. Map the Java driver option to the closest supported agent option (e.g. use 'retry' or 'retries' instead of unknown retry-related keys)
3. Check the applyCassandraURLParams switch in agents/drivers/cassandra-go/config.go for the exact list of supported keys

Example fix

// before
cassandra://127.0.0.1/myks?localdatacenter=dc1&retries=3
// after
cassandra://127.0.0.1/myks?retries=3

var supported = map[string]bool{
	"username": true, "password": true, "debug": true, "retries": true, "retry": true,
	"disableinitialhostlookup": true, "loadbalancing": true, "sslenginefactory": true,
	"usekrb5": true, "secureconnectbundle": true, "configfile": true,
	"kerberosqop": true, "saslqop": true, "kerberosdisablepafxfast": true, "disablepafxfast": true,
	"kerberosusekeytab": true, "usekeytab": true, "kerberosuseticketcache": true, "useticketcache": true,
	"compliancemode": true,
}
for k := range q {
	if !supported[strings.ToLower(k)] { return fmt.Errorf("unsupported param: %s", k) }
}

if err := parseCassandraConfig(dsn); err != nil {
	if strings.Contains(err.Error(), "unsupported Cassandra URL parameter") {
		return parseCassandraConfig(stripUnsupportedParams(dsn))
	}
	return err
}

When it happens

Trigger: DSN contains a parameter key outside the supported set, e.g. cassandra://host/db?consistency=quorum or ssl_engine=true; also keys with unexpected prefixes or casing variants not in the switch (key matching is normalized to lowercase but the option set is fixed).

Common situations: Reusing a Java Cassandra driver JDBC URL verbatim with options like localdatacenter, protocolversion, or jemalloc-style flags; typos in supported keys (retry vs retries); tooling that appends generic SQL params like applicationname.

Related errors

• retries must be between 0 and 1000
• custom Cassandra sslenginefactory is not supported by the na
• invalid requesttimeout: %w
• invalid connecttimeout: %w
• protocolversion must be between 3 and 5

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