Guide for upgrading Langfuse SDK versions, handling breaking changes between v2 and v3 (TypeScript) or v1 and v2 (Python), with automated codemod support.
Run npm list langfuse (Node) or pip show langfuse (Python) and review changelogs.
Key v3 changes: named exports, sync trace(), flushAsync() replaces flush(), camelCase usage keys.
Create chore/upgrade-langfuse branch. Run npm install langfuse@latest. Run tests.
Change import Langfuse to import { Langfuse }. Remove await from trace(). Replace flush() with flushAsync().
Update decorator from @langfuse.observe() to @observe(). Import from langfuse.decorators.
Use ts-morph script to auto-update imports and flush calls across the codebase.
Run tests verifying trace creation, generation usage format, and flush behavior.
See detailed implementation for advanced patterns.
| Error | Cause | Solution |
|---|---|---|
| Import error | Changed export | Use named import { Langfuse } |
| Type error on usage | Key name change | Use camelCase keys |
| flush() not found | Method renamed | Use flushAsync() |
| Decorator error | New import path | Import from langfuse.decorators |
| Feature | v2.x | v3.x | Migration |
|---|---|---|---|
| Default import | import Langfuse |
import { Langfuse } |
Update imports |
trace() return |
Promise<Trace> |
Trace |
Remove await |
flush() |
Sync | N/A | Use flushAsync() |
| Usage keys | snake_case |
camelCase |
Update all usage objects |
