{"record":{"id":"a5ba71a34e3be156","repo":"n8n-io/n8n","slug":"opentelemetry-active-span-callback-is-required","errorCode":null,"errorMessage":"OpenTelemetry active span callback is required.","messagePattern":"OpenTelemetry active span callback is required\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/@n8n/agents/src/sdk/metadata-enriched-tracer.ts","lineNumber":52,"sourceCode":"\tstartActiveSpan<F extends (span: Span) => unknown>(\n\t\tname: string,\n\t\toptionsOrFn: SpanOptions | F,\n\t\tcontextOrFn?: Context | F,\n\t\tfn?: F,\n\t): ReturnType<F> {\n\t\tif (typeof optionsOrFn === 'function') {\n\t\t\treturn this.delegate.startActiveSpan(name, optionsOrFn);\n\t\t}\n\n\t\tconst options = {\n\t\t\t...optionsOrFn,\n\t\t\tattributes: { ...this.attributes, ...optionsOrFn.attributes },\n\t\t};\n\t\tif (typeof contextOrFn === 'function') {\n\t\t\treturn this.delegate.startActiveSpan(name, options, contextOrFn);\n\t\t}\n\t\tif (contextOrFn === undefined || fn === undefined) {\n\t\t\tthrow new Error('OpenTelemetry active span callback is required.');\n\t\t}\n\n\t\treturn this.delegate.startActiveSpan(name, options, contextOrFn, fn);\n\t}\n}\n\nexport function createMetadataEnrichedTracer(\n\ttracer: Tracer,\n\tmetadata: Record<string, AttributeValue> | undefined,\n): Tracer {\n\tif (!metadata || Object.keys(metadata).length === 0) return tracer;\n\n\tconst attributes = Object.fromEntries(\n\t\tObject.entries(metadata).map(([key, value]) => [`ai.telemetry.metadata.${key}`, value]),\n\t);\n\treturn new MetadataEnrichedTracer(tracer, attributes);\n}\n","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/agents/src/sdk/metadata-enriched-tracer.ts#L34-L70","documentation":"Thrown by MetadataEnrichedTracer.startActiveSpan when the call resolves optionsOrFn to a SpanOptions object but neither contextOrFn nor fn is a function — i.e. the caller invoked the three-or-four-arg overload without supplying the required active-span callback. The OpenTelemetry Tracer contract requires the callback so the span can be activated around its execution.","triggerScenarios":"Only reachable when startActiveSpan is called with (name, SpanOptions, Context | undefined, undefined) — i.e. the callback argument is missing while earlier args are objects. Through typed TypeScript the overload signatures forbid this; it surfaces from JS callers, any/unknown-typed call sites, or as-casts that defeat the overloads.","commonSituations":"Third-party telemetry adapters forwarding variadic args into startActiveSpan; reflection-based tracer wrappers that drop the callback; misuse via cast (tracer as any).startActiveSpan(name, opts, ctx).","solutions":["Always pass the callback as the final argument: startActiveSpan(name, opts, fn) or startActiveSpan(name, opts, context, fn).","When forwarding variadic args, normalize to one of the documented overload shapes before delegating.","Avoid as-casts on the Tracer; let TypeScript enforce the overload."],"exampleFix":"// before\n(tracer as any).startActiveSpan('span', { attributes });\n// after\ntracer.startActiveSpan('span', { attributes }, (span) => {\n  try { /* work */ } finally { span.end(); }\n});","handlingStrategy":"validation","validationCode":"function assertActiveSpanCallback(args: unknown[]) {\n  const last = args[args.length - 1];\n  if (typeof last !== 'function') {\n    throw new TypeError('startActiveSpan requires a callback as the final argument');\n  }\n}","typeGuard":"function hasSpanCallback(args: unknown[]): boolean {\n  return typeof args[args.length - 1] === 'function';\n}","tryCatchPattern":null,"preventionTips":["Always invoke startActiveSpan with the callback in the final position.","Avoid `as any` on the Tracer interface; keep the overload signatures enforcing the callback.","When forwarding variadic args in a wrapper, normalize to (name, opts, fn) before delegating."],"tags":["opentelemetry","tracer","telemetry","misuse"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}