fix(langchain): handle null tokenUsage

[hassiebp]

Disclaimer: Experimental PR review

Greptile Summary

This PR is a targeted one-line fix for a crash in handleLLMEnd within the LangChain callback handler. When extractUsageMetadata returns undefined and output.llmOutput?.["tokenUsage"] is explicitly null (rather than undefined), the nullish-coalescing chain previously resolved to null. This caused a TypeError on the following lines that use the in operator (e.g., "promptTokens" in llmUsage), since in cannot operate on null. Adding ?? {} as a final fallback ensures llmUsage is always a safe object.

• Root cause: ?? only guards against null/undefined on its left side; it does not prevent null from propagating as the resolved value when that null is itself the result of the chain.
• Fix: Appending ?? {} guarantees llmUsage is at minimum an empty object, making all downstream in checks and optional-chain accesses safe.
• Impact: No functional regression — an empty object produces all-undefined usage fields, which is the same effective result as before (no usage data), but without the crash.

Confidence Score: 5/5

Safe to merge — the fix is minimal, correct, and eliminates a crash without changing intended behavior.

No P0 or P1 issues found. The one-line change correctly addresses the null-crash bug, all downstream consumers of llmUsage already handle undefined values gracefully via optional chaining, and the empty-object fallback is a well-established pattern for this type of nullish guard.

No files require special attention.

Important Files Changed

Filename	Overview
packages/langchain/src/CallbackHandler.ts	Adds a ?? {} fallback so llmUsage is never null when output.llmOutput?.["tokenUsage"] is explicitly null, preventing a TypeError from the subsequent "in" operator checks.

Sequence Diagram

sequenceDiagram
    participant LC as LangChain
    participant CB as CallbackHandler
    participant EU as extractUsageMetadata()

    LC->>CB: handleLLMEnd(output, runId)
    CB->>CB: get lastResponse from output.generations
    CB->>EU: extractUsageMetadata(lastResponse)
    EU-->>CB: UsageMetadata | undefined

    alt extractUsageMetadata returned value
        CB->>CB: llmUsage = UsageMetadata
    else null/undefined → check tokenUsage
        CB->>CB: llmUsage = output.llmOutput?.["tokenUsage"]
        alt tokenUsage is null (bug case fixed by PR)
            CB->>CB: llmUsage = {} (fallback default)
        end
    end

    CB->>CB: build usageDetails { input, output, total }
    Note over CB: "in" operator safe — llmUsage is never null
    CB->>CB: handleOtelSpanEnd(runId, usageDetails, ...)

Loading

_{Reviews (1): Last reviewed commit: "fix(langchain): handle null tokenUsage" | Re-trigger Greptile}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-js	Ready	Preview	Apr 1, 2026 8:39am

[github-actions]

@claude review

[claude]

LGTM — simple null-safety fix.

Extended reasoning...

Overview

Single-line change in packages/langchain/src/CallbackHandler.ts: adds ?? {} as a final fallback when computing llmUsage in handleLLMEnd. This prevents llmUsage from being null when output.llmOutput["tokenUsage"] is explicitly null (not undefined), which the ?? operator would not catch without this addition.

Security risks

None. This is purely a defensive null-guard on an internal value; no auth, crypto, or data-exposure paths are touched.

Level of scrutiny

Low. The change is mechanical and isolated to a single expression. The downstream usage of llmUsage includes "promptTokens" in llmUsage, which would throw a TypeError on a null value — the empty-object fallback is the correct fix.

Other factors

No bugs reported by the automated hunting system. Change touches no CODEOWNER-sensitive paths and follows the existing pattern in the file.