t8y2/dbx · error

invalid keepalive option: %w

Error message

invalid keepalive option: %w

What it means

The 'keepalive' URL parameter must parse as a boolean via strconv.ParseBool. Invalid values are rejected with this wrapped error during DSN parsing, before a session is created. keepalive enables TCP keep-alive probes on connections.

Source

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

				return fmt.Errorf("invalid ssl option: %w", err)
			}
			config.ssl = enabled
		case "hostverification", "verifyhostname", "sslhostnameverification", "hostnameverification":
			enabled, err := strconv.ParseBool(value)
			if err != nil {
				return fmt.Errorf("invalid host verification option: %w", err)
			}
			config.hostVerification = enabled
		case "tcpnodelay":
			enabled, err := strconv.ParseBool(value)
			if err != nil {
				return fmt.Errorf("invalid tcpnodelay option: %w", err)
			}
			config.tcpNoDelay = enabled
		case "keepalive":
			enabled, err := strconv.ParseBool(value)
			if err != nil {
				return fmt.Errorf("invalid keepalive option: %w", err)
			}
			config.keepAlive = enabled
		case "user":
			config.username = value
		case "password":
			config.password = value
		case "debug":
			enabled, err := strconv.ParseBool(value)
			if err != nil {
				return fmt.Errorf("invalid debug option: %w", err)
			}
			config.debug = enabled
		case "retries":
			count, err := strconv.Atoi(value)
			if err != nil || count < 0 || count > 1000 {
				return fmt.Errorf("retries must be between 0 and 1000")
			}
			config.retryCount = count

View on GitHub (pinned to c0390bff16)

Solutions

1. Use keepalive=true or keepalive=false (also accepted: 1/0, t/f, TRUE/FALSE in any ParseBool-accepted casing).
2. Trim whitespace/newlines from values before building the URL.
3. Remove the parameter to keep the driver's default keep-alive behavior.
4. Standardize boolean serialization (true/false) across all services generating Cassandra URLs.

Example fix

// before
cassandra://host:9042?keepalive=yes
// after
cassandra://host:9042?keepalive=true

v := strings.TrimSpace(keepalive)
if _, err := strconv.ParseBool(v); err != nil {
	return fmt.Errorf("keepalive must be true/false/1/0, got %q", keepalive)
}

func isParseBoolValue(v string) bool {
	_, err := strconv.ParseBool(v)
	return err == nil
}

cfg, err := parseCassandraConfig(dsn)
if err != nil {
	if strings.Contains(err.Error(), "invalid keepalive option") {
		return fmt.Errorf("keepalive accepts only ParseBool values: %w", err)
	}
	return err
}

When it happens

Trigger: keepalive=yes, keepalive=enabled, keepalive= (empty value from an unset env var), or keepalive=true (trailing newline) in a cassandra:// URL.

Common situations: Inconsistent boolean conventions across config files (some use yes/no, some true/false), CI secrets with trailing whitespace, or documentation examples copied verbatim with unsupported literals.

Related errors

• invalid tcpnodelay option: %w
• invalid ssl option: %w
• invalid host verification option: %w
• invalid requesttimeout: %w
• invalid connecttimeout: %w

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