openzipkin/zipkin · error · IllegalArgumentException

dateSeparator must be empty or a single character

Error message

dateSeparator must be empty or a single character

What it means

ZipkinElasticsearchStorageProperties.setDateSeparator throws IllegalArgumentException ('dateSeparator must be empty or a single character') when the date separator used in daily ES index names is more than one character after trimming. Index names are built as zipkin-span-YYYY<sep>MM<sep>DD, so a multi-character separator would create invalid/unpredictable index patterns; only '' or one character (typically '-') is allowed.

Source

Thrown at zipkin-server/src/main/java/zipkin2/server/internal/elasticsearch/ZipkinElasticsearchStorageProperties.java:264

    this.indexShards = indexShards;
  }

  public Boolean isEnsureTemplates() {
    return ensureTemplates;
  }

  public void setEnsureTemplates(Boolean ensureTemplates) {
    this.ensureTemplates = ensureTemplates;
  }

  public String getDateSeparator() {
    return dateSeparator;
  }

  public void setDateSeparator(String dateSeparator) {
    String trimmed = dateSeparator.trim();
    if (trimmed.length() > 1) {
      throw new IllegalArgumentException("dateSeparator must be empty or a single character");
    }
    this.dateSeparator = dateSeparator;
  }

  public Integer getIndexReplicas() {
    return indexReplicas;
  }

  public void setIndexReplicas(Integer indexReplicas) {
    this.indexReplicas = indexReplicas;
  }

  public String getUsername() {
    return username;
  }

  public void setUsername(String username) {
    this.username = emptyToNull(username);

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. Use a single character, e.g. zipkin.storage.elasticsearch.dateSeparator=-
2. Use an empty value if indices should have no separator
3. Remove accidental extra characters or whitespace inside the separator value

Example fix

# before
zipkin.storage.elasticsearch.dateSeparator=--

# after
zipkin.storage.elasticsearch.dateSeparator=-

String sep = props.getProperty("zipkin.storage.elasticsearch.dateSeparator", "-");
if (sep.trim().length() > 1) throw new IllegalArgumentException("dateSeparator must be '' or one char");

When it happens

Trigger: Setting zipkin.storage.elasticsearch.dateSeparator to values like '--', '..', or 'day' via properties, env var ZIPKIN_STORAGE_ELASTICSEARCH_DATESEPARATOR, or the StorageComponent builder.

Common situations: Copy-paste config with quotes or spaces ('- ' trims fine but '--' does not), migration from an old setup using a different separator format, or misunderstanding the property as a date format string.

Related errors

• empty {name} property in {fileName}
• concurrency < 1
• rate should be between 0 and 1: was {}
• clientProps is empty
• consumerProps is empty

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