detected no advertised-hostname key or empty value for trans

Error message

detected no advertised-hostname key or empty value for translator plugin options

What it means

The fixed address translator distinguishes Cassandra nodes by port, so it needs each node's advertised hostname. GetTranslator looks up key advertised-hostname in AddressTranslator.Options; if the key is absent or its value is an empty string, it returns this error.

Source

Thrown at common/persistence/nosql/nosqlplugin/cassandra/translator/fixed_address_translator.go:65

// and it will always return same fixed ip based on what advertised-hostname is resolved to. That IP address,
// from client's perspective, might be, for example, an IP address of a load balancer which is reachable from client.
// As the IP address of all nodes are some, the difference between the nodes can be achieved by running them on
// a different port for each node.
// see also https://github.com/gocql/gocql/pull/1635
func (plugin *FixedAddressTranslatorPlugin) GetTranslator(cfg *config.Cassandra) (gocql.AddressTranslator, error) {
	if cfg.AddressTranslator == nil {
		return nil, errors.New("there is no addressTranslator configuration in cassandra configuration")
	}

	opts := cfg.AddressTranslator.Options
	if opts == nil {
		return nil, errors.New("there are no options for translator plugin")
	}

	advertisedHostname, found := opts[advertisedHostnameKey]

	if !found || len(advertisedHostname) == 0 {
		return nil, errors.New("detected no advertised-hostname key or empty value for translator plugin options")
	}

	var resolvedIp net.IP = nil
	ips, _ := net.LookupIP(advertisedHostname)
	for _, ip := range ips {
		if ipv4 := ip.To4(); ipv4 != nil {
			resolvedIp = ipv4
			break
		}
	}

	if resolvedIp == nil {
		return nil, fmt.Errorf("no resolved IP for advertised hostname %q", advertisedHostname)
	}

	return gocql.AddressTranslatorFunc(func(addr net.IP, port int) (net.IP, int) {
		return resolvedIp, port
	}), nil

View on GitHub (pinned to bde624efd1)

Solutions

Set options.advertised-hostname to a non-empty hostname or IP per Cassandra node
Fix the exact key spelling: advertised-hostname
Ensure the templating source (env var, helm value) that feeds advertised-hostname is actually populated

Example fix

// before
addressTranslator:
  options:
    server-address: "127.0.0.1"
// after
addressTranslator:
  options:
    server-address: "127.0.0.1"
    advertised-hostname: "cassandra-0"

Defensive patterns

Strategy: validation

Validate before calling

opts := cfg.AddressTranslator.Options
v, ok := opts["advertised-hostname"]
if !ok || len(v) == 0 {
    return errors.New("advertised-hostname must be set and non-empty")
}
if _, err := net.LookupIP(v); err != nil {
    return fmt.Errorf("advertised-hostname %q not resolvable: %w", v, err)
}

Prevention

Use the exact key spelling advertised-hostname (hyphenated, lowercase)
Ensure templating always populates the value; fail deploys on empty node hostnames
Spot-check resolution of the hostname from the client's network

When it happens

Trigger: Calling GetTranslator with Options non-nil but missing the advertised-hostname key, or with options: {advertised-hostname: ""}.

Common situations: Typo in the key name (e.g. advertisedHostname or advertised_host); leaving the value empty in templated config because a node env var was unset; copying config from docs that used a different plugin's option names.

Related errors

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/629e00cfb51640cf. Report an issue: GitHub.