t8y2/dbx · error

invalid %s: expected V3, V4, or V5

Error message

invalid %s: expected V3, V4, or V5

What it means

hoconProtocolVersion throws this when the protocol-version config value is a HOCON type other than Int or String (e.g. a boolean, object, or array). Only integer values 3–5 or strings like "V3", "4", "v5" are accepted.

Source

Thrown at agents/drivers/cassandra-go/config_file.go:461

			return value, ok, err
		}
	}
	return false, false, nil
}

func hoconProtocolVersion(config *hocon.Config, path string) (int, bool, error) {
	value := config.Get(path)
	if value == nil {
		return 0, false, nil
	}
	var raw string
	switch typed := value.(type) {
	case hocon.Int:
		raw = strconv.Itoa(int(typed))
	case hocon.String:
		raw = string(typed)
	default:
		return 0, false, fmt.Errorf("invalid %s: expected V3, V4, or V5", path)
	}
	raw = strings.TrimPrefix(strings.ToUpper(strings.TrimSpace(raw)), "V")
	version, err := strconv.Atoi(raw)
	if err != nil || version < 3 || version > 5 {
		return 0, false, fmt.Errorf("invalid %s: expected V3, V4, or V5", path)
	}
	return version, true, nil
}

View on GitHub (pinned to c0390bff16)

Solutions

1. Set the key to a scalar: an integer 3, 4, or 5, or a string like "V3"/"v4".
2. Fix any accidental nesting (braces/brackets) around the key so it points at a scalar value.
3. Check that a commented-out or merged HOCON substitution is not replacing the key with an object.

Example fix

// before
protocol-version = {}

// after
protocol-version = V4

func validateProtocolVersionScalar(cfg *hocon.Config, path string) error {
    v := cfg.Get(path)
    if v == nil {
        return nil
    }
    switch v.(type) {
    case hocon.Int, hocon.String:
        return nil
    default:
        return fmt.Errorf("%s must be an int 3-5 or a string like \"V4\", got %T", path, v)
    }
}

func isProtocolVersionScalar(v interface{}) bool {
    switch v.(type) {
    case hocon.Int, hocon.String:
        return true
    default:
        return false
    }
}

ver, ok, err := hoconProtocolVersion(cfg, "datastax-java-driver.advanced.protocol.version")
if err != nil {
    return fmt.Errorf("protocol version must be a scalar (V3/V4/V5): %w", err)
}

When it happens

Trigger: applyJavaDriverHOCON reading the protocol version key where the value is a non-scalar HOCON value (object, array, boolean, null).

Common situations: Nesting a protocol-version block by mistake so the key resolves to an object, or setting the key to an empty object/array due to a HOCON syntax slip.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• invalid %s: expected boolean
• invalid %s: %w
• Agent runtime thread limits must be positive
• H2 JDBC driver rejected URL: " + buildJdbcUrl(params)
• Custom H2 driver profile requires at least one JDBC JAR path

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