apache/druid · error · IllegalArgumentException

Value of dimension[ ] cannot be null

Error message

Value of dimension[%s] cannot be null

What it means

ServiceMetricEvent.Builder.setDimension(String dim, Object value) also validates the dimension VALUE: after checking the name, it rejects a null value with IAE "Value of dimension[%s] cannot be null". Both parts of a dimension must be present for the metric event to be well-formed.

Solutions

1. Default the value to a sentinel string like "none" or "unknown" when the source value is null.
2. Omit the setDimension call entirely when the value is unavailable.
3. Fix the producer of the value so it never returns null for this metric.
4. Wrap emission in a null-safe helper used by all monitor code.

Example fix

// before
String taskId = task.getId(); // may be null
builder.setDimension("taskId", taskId); // IAE: Value of dimension[taskId] cannot be null
// after
String taskId = task != null && task.getId() != null ? task.getId() : "unknown";
builder.setDimension("taskId", taskId);

if (value == null) { value = "unknown"; }
builder.setDimension(name, value);

try {
  builder.setDimension(name, value);
} catch (IllegalArgumentException e) {
  log.warn("Dropping dimension [%s]: value was null", name);
}

When it happens

Trigger: Calling builder.setDimension("host", null) or setDimension(name, someObjectThatIsNull) — the value argument is null while the name is non-null.

Common situations: Emitting metrics whose dimension value comes from an optional field (e.g. task status, container id) that is null at emit time; refactors that changed a value's type and made it nullable.

Related errors

• Dimension name 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/07584bdd91b999ba. Report an issue: GitHub.

Appendix: source

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

     *
     * @throws IAE if the dimension name is null.
     */
    public Builder setDimensionIfNotNull(String dim, Object value)
    {
      return value == null ? this : setDimension(dim, value);
    }

    /**
     * Adds a dimension to be emitted with this metric event.
     *
     * @throws IAE if the dimension name or the given value is null.
     */
    public Builder setDimension(String dim, Object value)
    {
      if (dim == null) {
        throw new IAE("Dimension name cannot be null");
      } else if (value == null) {
        throw new IAE("Value of dimension[%s] cannot be null", dim);
      }

      userDims.put(dim, value);
      return this;
    }

    public Object getDimension(String dim)
    {
      return userDims.get(dim);
    }

    public Builder setMetric(String metric, Number value)
    {
      if (Double.isNaN(value.doubleValue())) {
        throw new ISE("Value of NaN is not allowed!");
      }
      if (Double.isInfinite(value.doubleValue())) {
        throw new ISE("Value of Infinite is not allowed!");

View on GitHub (pinned to 9b90983fd2)