apache/druid · error · IllegalStateException

Key [ ] is not registered as a context key

Error message

Key [%s] is not registered as a context key

What it means

ResponseContext.BaseResponseContext.keyOf resolves a String name to a registered Key object and throws IllegalStateException when no key with that name has been registered. All response-context access must go through pre-registered keys, so an unregistered name is an invariant violation.

Solutions

1. Use keyOfOrNull(name) (the nullable variant) and handle the null case instead of keyOf
2. Register the key with registerKey/registerKeys before calling keyOf
3. Fix the key name typo; verify against the constants defined in ResponseContext.KeyType or the owning extension
4. Ensure all cluster nodes run the extensions that register the keys they exchange

Example fix

// before
Key key = responseContext.keyOf("troughs"); // ISE if not registered
// after
Key key = responseContext.keyOfOrNull("troughs");
if (key != null) { /* use it */ }

if (context.keyOfOrNull(name) == null) {
  // handle unregistered key without throwing
  return null;
}

Key keyOrNull(ResponseContext ctx, String name) { return ctx.keyOfOrNull(name); }

try { key = ctx.keyOf(name); } catch (IllegalStateException e) { key = null; /* skip this context entry */ }

When it happens

Trigger: Calling keyOf("someName") where someName was never passed to registerKey/registerKeys — e.g. reading or writing a response context entry with a misspelled or extension-unknown key name.

Common situations: Typos in context key names; an extension that defines a key not loaded on this server (missing module); version skew where one node registers a key another node reads.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• Cannot join lookup with condition referring to non-key…
• Cannot join lookup with non-equi condition
• Joining against a ARRAY columns is not supported.
• Joining against a multi-value dimension is not supported.
• Key [ ] has already been registered as a context key

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

Appendix: source

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

     * 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.
     */
    public Key keyOf(String name)
    {
      Key key = registeredKeys.get(name);
      if (key == null) {
        throw new ISE("Key [%s] is not registered as a context key", name);
      }
      return key;
    }

    /**
     * Returns a registered key associated with the given name, or
     * {@code null} if the key is not registered. This form is for testing
     * and for deserialization when the existence of the key is suspect.
     */
    public Key find(String name)
    {
      return registeredKeys.get(name);
    }
  }

  protected abstract Map<Key, Object> getDelegate();

  public Map<String, Object> toMap()

View on GitHub (pinned to 9b90983fd2)