{"record":{"id":"fda5f6521f57a016","repo":"langchain-ai/langchain","slug":"if-env-var-is-set-handle-class-must-also-be-set-t","errorCode":null,"errorMessage":"If env_var is set, handle_class must also be set to a non-None value.","messagePattern":"If env_var is set, handle_class must also be set to a non-None value\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/core/langchain_core/tracers/context.py","lineNumber":191,"sourceCode":"    inheritable: bool,  # noqa: FBT001\n    handle_class: type[BaseCallbackHandler] | None = None,\n    env_var: str | None = None,\n) -> None:\n    \"\"\"Register a configure hook.\n\n    Args:\n        context_var: The context variable.\n        inheritable: Whether the context variable is inheritable.\n        handle_class: The callback handler class.\n        env_var: The environment variable.\n\n    Raises:\n        ValueError: If `env_var` is set, `handle_class` must also be set to a non-`None`\n            value.\n    \"\"\"\n    if env_var is not None and handle_class is None:\n        msg = \"If env_var is set, handle_class must also be set to a non-None value.\"\n        raise ValueError(msg)\n\n    _configure_hooks.append(\n        (\n            # the typings of ContextVar do not have the generic arg set as covariant\n            # so we have to cast it\n            cast(\"ContextVar[BaseCallbackHandler | None]\", context_var),\n            inheritable,\n            handle_class,\n            env_var,\n        )\n    )\n\n\nregister_configure_hook(run_collector_var, inheritable=False)\n","sourceCodeStart":173,"sourceCodeEnd":206,"githubUrl":"https://github.com/langchain-ai/langchain/blob/e32fa9a52eab3b61ad7a45399bfde59b3e580fc4/libs/core/langchain_core/tracers/context.py#L173-L206","documentation":"configure (from langchain_core.tracers.context) registers callback hooks tied to a context var. Because an env_var-based hook needs a handler class to instantiate when the env var is set, passing env_var without handle_class is rejected with ValueError.","triggerScenarios":"configure(context_var=my_var, env_var='MY_TRACER') with handle_class omitted or None.","commonSituations":"Custom tracing integrations copied from LangSmith's configure(...) call with the handler class accidentally removed; library code registering env-var-driven hooks dynamically.","solutions":["Pass handle_class together with env_var: configure(var, env_var='X', handle_class=MyHandler)","If no class-based handler is intended, drop env_var","Ensure handle_class is imported before the configure call (a failed import yielding None triggers this)"],"exampleFix":"# before\nconfigure(\n    context_var=my_var,\n    inheritable=False,\n    env_var=\"ENABLE_MY_TRACER\",\n)\n\n# after\nfrom my_pkg.tracers import MyHandler\n\nconfigure(\n    context_var=my_var,\n    inheritable=False,\n    env_var=\"ENABLE_MY_TRACER\",\n    handle_class=MyHandler,\n)","handlingStrategy":"validation","validationCode":"def safe_configure(context_var, *, env_var=None, handle_class=None, **kw):\n    if env_var is not None and handle_class is None:\n        msg = f\"env_var={env_var!r} requires handle_class\"\n        raise ValueError(msg)\n    return configure(context_var, env_var=env_var, handle_class=handle_class, **kw)","typeGuard":"def is_handler_class(cls: object) -> bool:\n    return isinstance(cls, type)","tryCatchPattern":"try:\n    configure(context_var=var, env_var=\"MY_TRACER\", handle_class=handler)\nexcept ValueError as e:\n    if \"handle_class\" in str(e):\n        from langchain_core.tracers import LangChainTracer\n        configure(context_var=var, env_var=\"MY_TRACER\", handle_class=LangChainTracer)\n    else:\n        raise","preventionTips":["Keep env_var and handle_class as an inseparable pair when copying configure() calls","Import handler classes at module top level so a missing import surfaces immediately","Add a unit test that exercises every registered hook configuration"],"tags":["langchain","tracing","callbacks","configuration"],"backgroundTag":null,"analyzedSha":"e32fa9a52eab3b61ad7a45399bfde59b3e580fc4","analyzedAt":"2026-08-14T18:42:09.092Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}