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

AbstractResponseMetadata.getRequired(key) retrieves a metadata entry and throws IllegalArgumentException when the key is absent (or mapped to null). It is a contract that the caller requires the value; use get(key) or containsKey(key) when absence is acceptable.

Solutions

1. Check containsKey(key) before calling getRequired, or use the nullable get(key) instead
2. Use the exact key constant defined by the library (e.g. AbstractUsage.REQUEST_LIMIT_REMAINING) rather than a hand-typed string
3. Verify the model/provider actually returns this metadata field; switch or upgrade provider/library if the field is genuinely missing

Example fix

// before
Integer tokens = metadata.getRequired("total_tokens");
// after
Integer tokens = metadata.containsKey("total_tokens") ? metadata.getRequired("total_tokens") : null;

if (!responseMetadata.containsKey(key)) {
    throw new IllegalStateException("Metadata missing required key: " + key);
}

try {
    T value = metadata.getRequired(key);
} catch (IllegalArgumentException e) {
    // fall back to default or log missing metadata key
    T value = defaultValue;
}

When it happens

Trigger: Calling getRequired("some-key") on response metadata (usage, model info, etc.) where the provider response did not include that key — e.g. requesting a field a particular model/provider never populates.

Common situations: Reading provider-specific metadata keys that not all models return; expecting a key under one name while the library stores it under another; older provider versions omitting fields newer code requires.

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/5a57435af9f53dd4. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-model/src/main/java/org/springframework/ai/model/AbstractResponseMetadata.java:64

	 * @param key key
	 * @param <T> value type
	 * @return entry or {@code null} if not present
	 */
	public <T> @Nullable T get(String key) {
		return (T) this.map.get(key);
	}

	/**
	 * Gets an entry from the context. Throws exception when entry is not present.
	 * @param key key
	 * @param <T> value type
	 * @return entry
	 * @throws IllegalArgumentException if not present
	 */
	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
	 */
	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
	 * @param <T> value type

View on GitHub (pinned to 98a7beda4f)