unsupported Cassandra SSL engine factory class: %s

Error message

unsupported Cassandra SSL engine factory class: %s

What it means

applyHOCONSSL (config_file.go:256) accepts only the Java driver's DefaultSslEngineFactory for `advanced.ssl-engine-factory.class` (case-insensitive simple class name). Any other SSL engine factory, such as the common Netty-based `ReceivedConfigSslEngineFactory` or a custom one, is rejected because the Go driver cannot use JVM SSL engines; native dbx.cassandra.tls settings are the supported path.

Source

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

		config.kerberos.useKeytab = value
		config.kerberos.useKeytabSet = true
	}
	if value, ok, err := firstHOCONBool(parsed, loginPrefix+"useTicketCache", loginPrefix+"use-ticket-cache"); err != nil {
		return err
	} else if ok {
		config.kerberos.useTicketCache = value
		config.kerberos.useTicketCacheSet = true
	}
	return nil
}

func applyHOCONSSL(config *cassandraConfig, parsed *hocon.Config) error {
	prefix := javaDriverConfigPrefix + "advanced.ssl-engine-factory."
	if value, ok, err := hoconString(parsed, prefix+"class"); err != nil {
		return err
	} else if ok {
		if !strings.EqualFold(simpleClassName(value), "DefaultSslEngineFactory") {
			return fmt.Errorf("unsupported Cassandra SSL engine factory class: %s", value)
		}
		config.ssl = true
	}
	if value, ok, err := hoconBool(parsed, prefix+"hostname-validation"); err != nil {
		return err
	} else if ok {
		config.hostVerification = value
		config.ssl = true
	}
	for _, path := range []string{prefix + "truststore-path", prefix + "keystore-path"} {
		if value, ok, err := hoconString(parsed, path); err != nil {
			return err
		} else if ok && value != "" {
			return fmt.Errorf("Java truststore and keystore files are not supported; use dbx.cassandra.tls PEM paths")
		}
	}
	return nil
}

View on GitHub (pinned to c0390bff16)

Solutions

Set `advanced.ssl-engine-factory.class` to DefaultSslEngineFactory in the HOCON file.
If you need custom TLS material (client certs, custom CA), remove the Java-driver SSL engine config and use the native `dbx.cassandra.tls.ca-cert-path`, `client-cert-path`, and `client-key-path` options instead.
Configure hostname verification via the native `dbx.cassandra.tls.hostname-verification` key rather than a custom engine factory.
If a custom engine factory was essential, replicate its behavior (e.g. SNI/hostname rules) at the TLS-terminating layer or in the Go TLS config options exposed by the library.

Example fix

// before (application.conf)
datastax-java-driver {
  advanced.ssl-engine-factory.class = com.datastax.oss.driver.internal.core.ssl.NettySslEngineFactory
}
// after
datastax-java-driver {
  advanced.ssl-engine-factory.class = com.datastax.oss.driver.internal.core.ssl.DefaultSslEngineFactory
}

Defensive patterns

Strategy: validation

Validate before calling

func validateSslEngineFactory(cfg *hocon.Config) error {
    const key = "datastax-java-driver.advanced.ssl-engine-factory.class"
    if cfg.Get(key) == nil {
        return nil
    }
    v := cfg.GetString(key)
    simple := v[strings.LastIndex(v, ".")+1:]
    if !strings.EqualFold(simple, "DefaultSslEngineFactory") {
        return fmt.Errorf("unsupported ssl-engine-factory: %s", v)
    }
    return nil
}

Type guard

func isDefaultSslEngineFactory(class string) bool {
    return strings.EqualFold(class[strings.LastIndex(class, ".")+1:], "DefaultSslEngineFactory")
}

Try / catch

if err := applyCassandraConfigFile(cfgPath); err != nil {
    if strings.Contains(err.Error(), "unsupported Cassandra SSL engine factory") {
        log.Fatalf("only DefaultSslEngineFactory is supported; move custom TLS settings to dbx.cassandra.tls")
    }
    return err
}

Prevention

Configure TLS through native dbx.cassandra.tls keys, not Java engine factories.
Audit migrated configs for NettySslEngineFactory/CommonNameSslEngineFactory before use.
Add config CI that runs the loader against shipped application.conf files.

When it happens

Trigger: A HOCON file sets `datastax-java-driver.advanced.ssl-engine-factory.class` to anything other than DefaultSslEngineFactory, e.g. `com.datastax.oss.driver.internal.core.ssl.NettySslEngineFactory` or a custom class.

Common situations: Configs migrated from DSE Java driver 1.x that used CommonNameSslEngineFactory or a hostname-verification custom factory; enterprise setups with a bespoke SSL engine for client certificates.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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