apache/druid · error · IllegalStateException

Failed to parse metric dimensions and types

Error message

Failed to parse metric dimensions and types

What it means

StatsDEmitter's DimensionConverter loads a JSON file mapping metric names to StatsDMetric dimensions/types. If Jackson cannot parse the configured file as Map<String, StatsDMetric> (malformed JSON, wrong structure), readMap wraps the IOException in an ISE with this message.

Source

Thrown at extensions-contrib/statsd-emitter/src/main/java/org/apache/druid/emitter/statsd/DimensionConverter.java:95

  }

  private Map<String, StatsDMetric> readMap(ObjectMapper mapper, String dimensionMapPath)
  {
    try {
      InputStream is;
      if (Strings.isNullOrEmpty(dimensionMapPath)) {
        log.info("Using default metric dimension and types");
        is = this.getClass().getClassLoader().getResourceAsStream("defaultMetricDimensions.json");
      } else {
        log.info("Using metric dimensions at types at [%s]", dimensionMapPath);
        is = new FileInputStream(new File(dimensionMapPath));
      }
      return mapper.readerFor(new TypeReference<Map<String, StatsDMetric>>()
      {
      }).readValue(is);
    }
    catch (IOException e) {
      throw new ISE(e, "Failed to parse metric dimensions and types");
    }
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Validate the dimensions JSON: top level must be an object mapping metric name -> {dimensions, metricType}.
2. Run the file through a JSON linter (jq . dimensions.json) to find syntax errors.
3. Check that each entry's fields match StatsDMetric's expected property names and types.
4. Ensure the file path configured points at the intended file, not an HTML error page or empty file.

Example fix

// before
{"metric1": ["dim1"]}
// after
{"metric1": {"dimensions": ["dim1"], "metricType": "timer"}}

JsonNode root = new ObjectMapper().readTree(dimensionFile);
if (!root.isObject()) throw new IllegalArgumentException("dimensions file must be a JSON object mapping metric name -> StatsDMetric");

try { converter = new DimensionConverter(mapper, dimensionFile); } catch (ISE e) { log.error("Invalid statsd dimensions file %s: %s", dimensionFile, e.getMessage()); throw e; }

When it happens

Trigger: statsd emitter configured with dimensionsFile whose content is invalid JSON, or valid JSON that does not match Map<String, StatsDMetric> (e.g. array at top level, missing metricType fields, wrong types for dimensions).

Common situations: Hand-edited dimensions JSON with a trailing comma; file written as a JSON array instead of object; copy-pasted config using snake_case fields not recognized by StatsDMetric; unreadable/garbled file contents.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Cannot deserialize type[%s] to an RoaringBitmap64Counter:
• Index[%d] >= size[%d]
• Reverse lookup not allowed.
• Serialization not supported here
• ColumnCapacityExceededException

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