LangChain Debug Bundle

Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Collect comprehensive debug information for LangChain issues including traces, versions, and reproduction steps.

Prerequisites

• LangChain installed
• Reproducible error condition
• Access to logs and environment

Instructions

Step 1: Collect Environment Info

Run pip show on all LangChain packages to gather versions, Python version, and platform info.

Step 2: Enable Full Tracing

Set langchain.debug = True and enable LangSmith tracing. Attach a DebugCallback that logs all LLM start/end/error events with timestamps.

Step 3: Create Minimal Reproduction

Write a standalone script that reproduces the issue with minimal code and redacted API keys.

Step 4: Generate Debug Bundle

Combine environment info, trace logs, and reproduction steps into a debug_bundle.json file.

See detailed implementation for complete debug callback and bundle generator code.

Output

• debug_bundle.json with full diagnostic information
• minimal_repro.py for issue reproduction
• Environment and version information
• Trace logs with timestamps

Error Handling

Issue	Cause	Solution
Callback not capturing	Not attached to LLM	Pass via callbacks= parameter
Large trace logs	Long-running operation	Filter by time range
API key in logs	Missing redaction	Always redact before sharing

Examples

Basic usage: Apply langchain debug bundle to a standard project setup with default configuration options.

Advanced scenario: Customize langchain debug bundle for production environments with multiple constraints and team-specific requirements.

Resources

• LangChain GitHub Issues
• LangSmith Tracing
• LangChain Discord

Next Steps

Use langchain-common-errors for quick fixes or escalate with the bundle.