npm / langfuse

langfuse

What changed in langfuse 5 to 6, from its official release notes, upgrade guides and advisories. Sources checked 2026-11-06.

24 breaking2 deprecations17 new APIs and options7 behavior and defaults

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli 0.2.11 on npm

langfuse 628 changes

Breaking changes 14

The legacy namespace and deprecated public API methods are removed; use their documented replacements.
6.0.0upgrade guide
Removed; create scores with api.scores.create([...]) instead.
6.0.0upgrade guide
Accepts an array of CreateScoreRequest objects and can report partial acceptance through accepted, rejected, and errors; the response no longer contains the score id.
6.0.0upgrade guide
Use this method to delete a score; it replaces api.legacy.scoreV1.delete(scoreId).
6.0.0upgrade guide
Now behaves like the former api.scoresV3.getManyV3; filter scores by id rather than scoreIds.
6.0.0upgrade guide
Removed with no alias; use api.scores.getMany for score reads.
6.0.0upgrade guide
Dataset items are now plain DatasetItem[] without link(); use the experiment runner instead.
6.0.0upgrade guide
The SDK requires Langfuse Cloud or self-hosted Langfuse v4.59.0 or later; self-hosted v3 and earlier v4 releases are unsupported.
6.0.0upgrade guide
The LangChain integration now requires @langchain/core@^1.0.0; older versions cause a peer dependency conflict.
6.0.0upgrade guide
Now sends scores to POST /api/public/scores using public-key authentication.
6.0.0upgrade guide
Deprecated top-level convenience methods such as getPrompt, getDataset, and fetchTrace are removed; use the managers or API client replacements.
6.0.0upgrade guide
Metadata values, including strings, are JSON-encoded on spans; custom processors and exporters reading these attributes need to parse them with JSON.parse().
6.0.0upgrade guide
v6 requires Node.js 22 or later; packages are compiled to ES2022, so bundles for older runtimes must transpile the SDK.
6.0.0upgrade guide
Removed along with span.setTraceIO() and createTraceAttributes(); set trace input and output on the root observation instead.
6.0.0upgrade guide

New APIs and options 9

Batch score creation accepts an array of CreateScoreRequest objects.
6.0.0upgrade guide
Set compression: "none" on LangfuseSpanProcessor to disable gzip compression when a proxy rejects compressed requests.
6.0.0upgrade guide
Experiment results now provide result.experimentUrl, linking directly to the experiment comparison view.
6.0.0upgrade guide
LangfuseClient now exposes getExperimentUrl(experimentId) to get an experiment URL.
6.0.0upgrade guide
LangfuseClient now exposes getProjectId().
6.0.0upgrade guide
Set to none to disable span-batch gzip compression when a proxy rejects compressed requests.
6.0.0upgrade guide
Dataset versions are recorded on experiment items using this attribute.
6.0.0upgrade guide
Metadata sent with v6 can be filtered by dotted paths such as a.b = 1; numeric and boolean comparisons are not supported yet.
6.0.0upgrade guide
Affected generated API methods now take an optional request argument before requestOptions; pass {} when supplying options to methods without query parameters or a body.
6.0.0upgrade guide

Behavior and default changes 5

Experiments are recorded through OpenTelemetry; sampled-out item traces do not appear in the experiment, while run-level scores are always stored.
6.0.0upgrade guide
A LangfuseSpanProcessor mask function receives decoded observation metadata, which may be a number, boolean, or object rather than a string.
6.0.0upgrade guide
Scores are sent in batches of up to 100 to POST /api/public/scores instead of the legacy ingestion endpoint; rejected scores in partial responses are logged and not retried.
6.0.0upgrade guide
Score methods validate input on the client and never throw; scores with an empty name or invalid value are logged and dropped.
6.0.0upgrade guide
Span batches are gzip-compressed on Node.js and Bun; browser and edge runtimes do not compress.
6.0.0upgrade guide

langfuse 522 changes

Breaking changes 10

Use this environment variable to set the release instead of the removed release trace attribute.
5.0.0upgrade guide
Use this environment variable to set the tracing environment instead of the removed environment trace attribute.
5.0.0upgrade guide
Now points to the Metrics v2 endpoint; use langfuse.api.legacy.metricsV1 for a self-hosted Langfuse v3 server.
5.0.0upgrade guide
Now points to the Observations v2 endpoint; use langfuse.api.legacy.observationsV1 for a self-hosted Langfuse v3 server.
5.0.0upgrade guide
Propagated metadata now requires Record<string, string> values, with values no longer than 200 characters.
5.0.0upgrade guide
By default, exports Langfuse-created spans, spans with gen_ai.* attributes, and spans from known LLM instrumentation scopes instead of exporting all spans.
5.0.0upgrade guide
A custom callback is a full override of the default span filter; compose with isDefaultExportSpan to extend the default behavior.
5.0.0upgrade guide
Trace updates are split among propagateAttributes(), setActiveTraceIO(), and setActiveTraceAsPublic().
5.0.0upgrade guide
Observation wrapper trace updates are split into propagateAttributes(), .setTraceIO(), and .setTraceAsPublic().
5.0.0upgrade guide
The transitional observationsV2, scoreV2, and metricsV2 aliases were removed; use the default resource names instead.
5.0.0upgrade guide

Deprecations 2

Deprecated for new code; set input and output on the root observation directly. It remains for backward compatibility with trace-level evaluators.
5.0.0upgrade guide
Deprecated for new code; set input and output on the root observation directly. It remains for backward compatibility with trace-level evaluators.
5.0.0upgrade guide

New APIs and options 8

Checks the default span-filter rules so custom shouldExportSpan logic can extend rather than replace them.
5.0.0upgrade guide
Provides the legacy v1 metrics resource, including for compatibility with self-hosted Langfuse v3.
5.0.0upgrade guide
Provides the legacy v1 observations resource, including for compatibility with self-hosted Langfuse v3.
5.0.0upgrade guide
Provides the legacy v1 score resource.
5.0.0upgrade guide
The v2 score resource is now the default Public API resource under this name.
5.0.0upgrade guide
Wraps a callback and applies correlating attributes to child observations created within its scope.
5.0.0upgrade guide
Replaces setting the trace's public attribute through updateActiveTrace().
5.0.0upgrade guide
Replaces setting the trace's public attribute through .updateTrace().
5.0.0upgrade guide

Behavior and default changes 2

Non-string traceMetadata values are serialized with JSON.stringify before being passed to propagateAttributes().
5.0.0upgrade guide
Correlating attributes propagate to every observation rather than living only on the trace, enabling single-table queries and improving query performance at scale.
5.0.0upgrade guide