Diagnose: token usage metadata missing from streaming responses

TL;DR: Symptom: usage_metadata is empty on streamed chunks. Confirm the provider, enable the streaming usage opt-in where required, and aggregate with the usage callback. Confirm Check the provider. Enable the streaming usage option on the integration (see the provider's integration page, e.g. the OpenAI chat integration's streaming usage metadata section).

The fix

Symptom

You stream a chat model and the usage metadata (input/output tokens) is missing or zero, while non-streamed invokes report it fine.

Confirm

Check the provider. OpenAI and Azure OpenAI chat completions require you to opt in to receiving token usage in streaming contexts; it is not returned by default. Other providers vary.

Cause

Streaming usage is a provider-side option, not a LangChain default. The chunks simply do not carry usage unless the integration asks for it.

Fix

1. Enable the streaming usage option on the integration (see the provider's integration page, e.g. the OpenAI chat integration's streaming usage metadata section).
2. Aggregate across calls with the callback instead of reading chunks by hand:

from langchain_core.callbacks import UsageMetadataCallbackHandler

callback = UsageMetadataCallbackHandler()
result = model.invoke("Hello", config={"callbacks": [callback]})
print(callback.usage_metadata)

or the context manager get_usage_metadata_callback.

Verify

Re-run the stream and confirm usage_metadata populates. If it is still empty, the provider does not return usage for that model or endpoint; check the provider docs.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Diagnose.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Diagnose behavior.

Edge cases

• The chunks simply do not carry usage unless the integration asks for it.

Diagnostic procedure grounded in the official models docs (token usage), verified 2026-09-26. Models: https://docs.langchain.com/oss/python/langchain/models