What causes "Key[%s] is required in map[%s]" in apache/druid?

Add the missing key to the map/config so it satisfies the contract (e.g. set 'dataSource' in the spec)

apache/druid · error · IllegalArgumentException

Key[ ] is required in map[ ]

Error message

Key[%s] is required in map[%s]

What it means

MapUtils.getString(map, key, defaultValue) throws this IAE when the key is absent (or mapped to null) AND the supplied defaultValue is null — i.e. the caller requested a required key by passing no default. The message shows the missing key and the whole map to aid diagnosis. If a non-null default is given, it is returned instead of throwing.

Solutions

Add the missing key to the map/config so it satisfies the contract (e.g. set 'dataSource' in the spec)
Pass a non-null default if the field is actually optional: MapUtils.getString(map, key, "default")
Validate required keys up front (Preconditions/checkArgument or a schema validator) to fail with a better message
Log/print the map contents shown in the error to spot typos in key names (case sensitivity matters)

Example fix

// before
String ds = MapUtils.getString(config, "dataSource"); // IAE if absent
// after
String ds = MapUtils.getString(config, "dataSource", "default-datasource");

Defensive patterns

Strategy: validation

Validate before calling

if (!config.containsKey("dataSource")) {
  throw new IllegalArgumentException("'dataSource' is required in config");
}

Type guard

static String requireString(Map<String, Object> map, String key) {
  Object v = map.get(key);
  if (v == null) throw new IllegalArgumentException("missing key: " + key);
  return v.toString();
}

Try / catch

try {
  dataSource = MapUtils.getString(config, "dataSource");
} catch (IllegalArgumentException e) {
  throw new SpecValidationException("Missing required 'dataSource' field in ingestion spec", e);
}

Prevention

Decide per key whether it is required (null default) or optional (explicit default)
Validate config maps against a schema at load time
Watch key spelling and case — the error prints the whole map for comparison
For optional fields always pass a non-null default explicitly

When it happens

Trigger: Calling MapUtils.getString(specMap, "dataSource") where 'dataSource' is missing and the third argument is null, or explicitly MapUtils.getString(map, key, null); also nested lookups where an outer key exists but the inner map lacks the requested key.

Common situations: Ingestion spec or task config maps missing mandatory fields (dataSource, topic, intervals); JSON payloads from clients omitting required properties; schema drift after a Druid version adds a required key.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/java/util/common/MapUtils.java:39

import java.util.Map;

/**
 */
public class MapUtils
{
  public static String getString(Map<String, Object> in, String key)
  {
    return getString(in, key, null);
  }

  public static String getString(Map<String, Object> in, String key, String defaultValue)
  {
    Object retVal = in.get(key);

    if (retVal == null) {
      if (defaultValue == null) {
        throw new IAE("Key[%s] is required in map[%s]", key, in);
      }

      return defaultValue;
    }

    return retVal.toString();
  }

  public static int getInt(Map<String, Object> in, String key, Integer defaultValue)
  {
    Object retVal = in.get(key);

    if (retVal == null) {
      if (defaultValue == null) {
        throw new IAE("Key[%s] is required in map[%s]", key, in);
      }

      return defaultValue;

View on GitHub (pinned to 9b90983fd2)