Checked other resources

• This is a bug, not a usage question.
• I used the GitHub search to find a similar question and didn't find it.
• I am sure that this is a bug in LangChain rather than my code.
• The bug is not resolved by updating to the latest stable version.
• This is not related to the langchain-community package.
• I posted a self-contained, minimal, reproducible example.

Package

langchain-core

Bug summary

Calling .with_structured_output(schema) on a RunnableWithFallbacks (e.g. a chat model wrapped with .with_fallbacks([fallback])) crashes with NameError: name 'Runnable' is not defined inside langchain_core/runnables/fallbacks.py:_returns_runnable.

The crash happens when _returns_runnable calls typing.get_type_hints(attr) on the bound method of the underlying chat model. get_type_hints evaluates string forward references against the function's __globals__ (the module where the method was defined). If that module doesn't have the referenced name in scope — which happens when a chat model inherits a method from a base class whose module uses forward refs that aren't importable from there — get_type_hints raises NameError and the entire __getattr__ lookup blows up.

This makes it impossible to use the otherwise-supported pattern of binding structured output to a fallback chain.

Reproducer

from langchain_xai import ChatXAI  # or any chat model whose with_structured_output annotation has unresolvable forward refs
from pydantic import BaseModel

class TestSchema(BaseModel):
    field: str

primary = ChatXAI(model="grok-4-1-fast-non-reasoning")
fallback = ChatXAI(model="grok-4-1-fast-non-reasoning")
chain_with_fallbacks = primary.with_fallbacks([fallback])

# This crashes:
chain = chain_with_fallbacks.with_structured_output(TestSchema)

Stack trace (truncated):

File ".../langchain_core/runnables/fallbacks.py", line 626, in __getattr__
    if _returns_runnable(attr):
File ".../langchain_core/runnables/fallbacks.py", line 652, in _returns_runnable
    return_type = typing.get_type_hints(attr).get("return")
File ".../typing.py", line 2315, in get_type_hints
    hints[name] = _eval_type(value, globalns, localns, type_params)
File ".../typing.py", line 947, in _evaluate
    eval(self.__forward_code__, globalns, localns),
File "<string>", line 1, in <module>
NameError: name 'Runnable' is not defined

Expected behavior

chain_with_fallbacks.with_structured_output(schema) should return a working structured-output chain (or at minimum, return the bare method without raising). Methods that genuinely return a Runnable and have resolvable annotations should still be re-wrapped to propagate fallbacks.

Actual behavior

__getattr__ raises NameError and the call site is left with no usable chain.

Workaround (currently in use)

Bind structured output to the primary and the fallback individually before composing the fallback chain:

primary_with_so = primary.with_structured_output(schema)
fallback_with_so = fallback.with_structured_output(schema)
chain = primary_with_so.with_fallbacks([fallback_with_so])

This works but is awkward — it forces callers to know about the failure mode of RunnableWithFallbacks.__getattr__ and reach into the underlying runnables.

Proposed fix

Make _returns_runnable defensive against get_type_hints failures. When the return type can't be determined (NameError from unresolvable forward refs, TypeError from unsupported callables, AttributeError from missing __annotations__), default to False and return the bare attribute. This preserves callability and only loses the automatic fallback re-wrapping for the introspection failure case — which is the safe default when we genuinely can't tell.

def _returns_runnable(attr: Any) -> bool:
    if not callable(attr):
        return False
    try:
        return_type = typing.get_type_hints(attr).get("return")
    except (NameError, TypeError, AttributeError):
        return False
    return bool(return_type and _is_runnable_type(return_type))

I have a branch with this fix plus a regression test (test_fallbacks_getattr_unresolvable_annotation) ready, verified to fail before the fix and pass after, with all 17 existing fallbacks tests still passing and make format/make lint/make test all green:

https://github.com/untilhamza/langchain/tree/fix/runnable-fallbacks-introspection-nameerror

Happy to open a PR once assigned.

System Info

• langchain-core: 1.2.16 (also reproduces on master)
• Python: 3.12
• OS: macOS