openzipkin/zipkin · error · NullPointerException

keyspace == null

Error message

keyspace == null

What it means

CassandraStorageBuilder.keyspace(String) throws NullPointerException ('keyspace == null') when the keyspace name is set to null. The keyspace (default 'zipkin3') determines where spans and indexes are stored; a null name cannot map to a Cassandra keyspace, so the builder fails fast instead of erroring later during session creation.

Source

Thrown at zipkin-storage/cassandra/src/main/java/zipkin2/storage/cassandra/CassandraStorageBuilder.java:148

    this.password = password;
    return (B) this;
  }

  /** Use ssl for connection. Defaults to false. */
  public B useSsl(boolean useSsl) {
    this.useSsl = useSsl;
    return (B) this;
  }

  /** Controls validation of Cassandra server hostname. Defaults to true. */
  public B sslHostnameValidation(boolean sslHostnameValidation) {
    this.sslHostnameValidation = sslHostnameValidation;
    return (B) this;
  }

  /** Keyspace to store span and index data. Defaults to "zipkin3" */
  public B keyspace(String keyspace) {
    if (keyspace == null) throw new NullPointerException("keyspace == null");
    this.keyspace = keyspace;
    return (B) this;
  }

  /** Override to control how sessions are created. */
  public B sessionFactory(CassandraStorage.SessionFactory sessionFactory) {
    if (sessionFactory == null) throw new NullPointerException("sessionFactory == null");
    this.sessionFactory = sessionFactory;
    return (B) this;
  }

  public B ensureSchema(boolean ensureSchema) {
    if (ensureSchema) {
      this.ensureSchema = Schema::ensure;
    } else {
      this.ensureSchema = Schema::validate;
    }
    return (B) this;

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Pass a keyspace name, e.g. keyspace("zipkin3")
2. Default null config values to "zipkin3" before calling the builder
3. Verify the env/property variable name in the deployment matches the version of Zipkin in use

Example fix

// before
String ks = System.getenv("CASSANDRA_KEYSPACE"); // null
builder.keyspace(ks);

// after
String ks = System.getenv("CASSANDRA_KEYSPACE");
builder.keyspace(ks != null ? ks : "zipkin3");

String keyspace = System.getenv("CASSANDRA_KEYSPACE");
builder.keyspace(keyspace != null ? keyspace : "zipkin3");

When it happens

Trigger: Calling keyspace(null), or passing a null from property resolution where zipkin.storage.cassandra.keyspace / CASSANDRA_KEYSPACE was not configured in a custom embedding (the server's property binding supplies a default, direct builder use does not).

Common situations: Embedding the Cassandra storage module programmatically and forgetting the keyspace; env var not set in the container; property renamed during an upgrade leaving the old key unset.

Related errors

• contactPoints == null
• sessionFactory == null
• Cannot read keyspace metadata for keyspace: %s and cluster:
• hostPort == null
• bootstrapServers == null

AI-assisted analysis of openzipkin/zipkin@878ce2a1fa (2026-08-14). Data as JSON: /api/errors/a91330a76ed60b14. Report an issue: GitHub.