spring-projects/spring-ai · error · IllegalArgumentException

Context does not have an entry for key

Error message

Context does not have an entry for key [%s]

What it means

MutableResponseMetadata.getRequired(key) returns the value for a metadata key and throws IllegalArgumentException if the key is absent or null. It is the mutable counterpart of AbstractResponseMetadata.getRequired and carries the same requirement contract.

Solutions

1. Ensure put(key, value) is called with the exact key before getRequired is invoked
2. Guard with containsKey(key) or fall back to get(key) when the value is optional
3. Log/inspect the metadata map contents (keySet()) to confirm the key name and population timing

Example fix

// before
String id = metadata.getRequired("request-id");
// after
String id = metadata.containsKey("request-id")
    ? metadata.getRequired("request-id")
    : UUID.randomUUID().toString();

if (mutableMetadata == null || !mutableMetadata.containsKey(key)) {
    throw new IllegalStateException("Key not populated before read: " + key);
}

try {
    T value = mutableMetadata.getRequired(key);
} catch (IllegalArgumentException e) {
    // key not set yet — initialize or skip
    mutableMetadata.put(key, initialValue);
    T value = initialValue;
}

When it happens

Trigger: Calling getRequired on a mutable metadata map that was never populated with that key — e.g. reading a key before the framework/put() populated it, or using a key the upstream model response never contained.

Common situations: Code that builds or mutates response metadata itself and forgets a put() for the required key; reading metadata mid-pipeline before an enriching step ran; typos in key names.

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

• Context does not have an entry for key
• DataSource must be set (either via dataSource() or…
• Documents list cannot be empty
• Expected a List, but got:
• Failed to extract all URI variables from request URI

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/e6d815b34c5f1241. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-model/src/main/java/org/springframework/ai/model/MutableResponseMetadata.java:75

	 * @return the previous value associated with the key, or null if there was no mapping
	 * for the key
	 */
	public Object remove(Object key) {
		return this.map.remove(key);
	}

	/**
	 * Gets an entry from the context. Throws exception when entry is not present.
	 * @param key key
	 * @param <T> value type
	 * @throws IllegalArgumentException if not present
	 * @return entry
	 */
	@Override
	public <T> T getRequired(Object key) {
		T object = (T) this.map.get(key);
		if (object == null) {
			throw new IllegalArgumentException("Context does not have an entry for key [" + key + "]");
		}
		return object;
	}

	/**
	 * Checks if context contains a key.
	 * @param key key
	 * @return {@code true} when the context contains the entry with the given key
	 */
	@Override
	public boolean containsKey(Object key) {
		return this.map.containsKey(key);
	}

	/**
	 * Returns an element or default if not present.
	 * @param key key
	 * @param defaultObject default object to return

View on GitHub (pinned to 98a7beda4f)