apache/druid · error · IllegalArgumentException

Dimension name cannot be null

Error message

Dimension name cannot be null

What it means

ServiceMetricEvent.Builder.setDimension(String dim, String[] values) validates that the dimension name is non-null before adding it to the event's dimension map. A null dimension name would produce a malformed metric event that downstream consumers cannot key on, so IAE is thrown eagerly.

Solutions

1. Fix the caller to pass a non-null dimension name; trace where the name is computed and supply a default.
2. Substitute a placeholder like "unknown" when the dimension source value is null.
3. Skip adding the dimension (or the whole event) when the name is unavailable, if the metric remains meaningful.
4. Add an upstream null-check with a clear log message so the root cause is visible.

Example fix

// before
String dataSource = taskInfo == null ? null : taskInfo.getDataSource();
builder.setDimension(dataSource, new String[]{"task"}); // IAE if null
// after
String dataSource = taskInfo == null ? null : taskInfo.getDataSource();
builder.setDimension(dataSource != null ? dataSource : "unknown", new String[]{"task"});

if (dimName == null) { dimName = "unknown"; }
builder.setDimension(dimName, values);

try {
  builder.setDimension(dim, values);
} catch (IllegalArgumentException e) {
  log.warn(e, "Skipping metric with null dimension");
}

When it happens

Trigger: Calling builder.setDimension(null, new String[]{...}) with a null dimension name. Note this is the String[] overload; the check fires only on a null dim name, not null values.

Common situations: Metric-emitting code that computes a dimension name dynamically (e.g. from a task ID or label) and gets null when the source value is missing; monitor code emitting service metrics during Druid startup before identifiers are known.

Related errors

• Value of dimension[ ] cannot be null
• Cannot have a null/empty columns
• Encountered metric with null or empty name at position
• Escape must be null or a single character
• Illegal number of fields

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/66f923125181174f. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/java/util/emitter/service/ServiceMetricEvent.java:152

   */
  public static class Builder extends ServiceEventBuilder<ServiceMetricEvent>
  {
    private final Map<String, Object> userDims = new TreeMap<>();
    private String feed = "metrics";
    private String metric;
    private Number value;
    private DateTime createdTime;

    public Builder setFeed(String feed)
    {
      this.feed = feed;
      return this;
    }

    public Builder setDimension(String dim, String[] values)
    {
      if (dim == null) {
        throw new IAE("Dimension name cannot be null");
      }

      userDims.put(dim, Arrays.asList(values));
      return this;
    }

    /**
     * Adds a dimension to be emitted with this metric event, only if the given
     * value is not null.
     *
     * @throws IAE if the dimension name is null.
     */
    public Builder setDimensionIfNotNull(String dim, Object value)
    {
      return value == null ? this : setDimension(dim, value);
    }

    /**

View on GitHub (pinned to 9b90983fd2)