apache/druid · error · IllegalArgumentException

Key [ ] has already been registered as a context key

Error message

Key [%s] has already been registered as a context key

What it means

ResponseContext.BaseResponseContext.registerKey maintains a registry of valid context keys and throws IllegalArgumentException when a key with the same name is already registered. This protects against duplicate definitions of response context keys across server components.

Solutions

  1. Check keyOf(name)/registration before calling registerKey, or register only once at static initialization
  2. Rename your key to a unique, namespaced string (e.g. prefix with extension name)
  3. Catch IllegalArgumentException from registerKey and treat it as a no-op if the existing key is equivalent
  4. Register all keys together via registerKeys at a single well-defined initialization point

Example fix

// before
responseContext.registerKey(MY_KEY);
responseContext.registerKey(MY_KEY); // IAE
// after
if (responseContext.keyOfOrNull(MY_KEY.getName()) == null) {
  responseContext.registerKey(MY_KEY);
}
Defensive patterns

Strategy: try-catch

Validate before calling

// guard against duplicate registration
if (context.keyOfOrNull(key.getName()) == null) {
  context.registerKey(key);
}

Type guard

boolean isRegistered(ResponseContext ctx, String name) { return ctx.keyOfOrNull(name) != null; }

Try / catch

try { ctx.registerKey(key); } catch (IllegalArgumentException e) { log.debug("key already registered: %s", key.getName()); }

Prevention

When it happens

Trigger: Calling registerKey (directly or via registerKeys) with a Key whose getName() collides with a previously registered key, e.g. two extensions registering the same response context key name.

Common situations: Two Druid extensions or modules defining response header/context keys with identical names; re-registering keys during component restart without checking the registry; duplicate constant definitions after a merge.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/query/context/ResponseContext.java:519

    }

    /**
     * Returns the single, global key registry for this server.
     */
    public static Keys instance()
    {
      return INSTANCE;
    }

    /**
     * Primary way of registering context keys.
     *
     * @throws IllegalArgumentException if the key has already been registered.
     */
    public void registerKey(Key key)
    {
      if (registeredKeys.putIfAbsent(key.getName(), key) != null) {
        throw new IAE("Key [%s] has already been registered as a context key", key.getName());
      }
    }

    /**
     * Register a group of keys.
     */
    public void registerKeys(Key[] keys)
    {
      for (Key key : keys) {
        registerKey(key);
      }
    }

    /**
     * Returns a registered key associated with the name {@param name}.
     *
     * @throws IllegalStateException if a corresponding key has not been registered.
     */

View on GitHub (pinned to 9b90983fd2)