langfuse/langfuse · error · Error

Failed to create span

Error message

Failed to create span

What it means

Generic Error thrown by POST /api/public/spans when span ingestion did not report exactly one success. Upstream ingestion errors are surfaced separately (their status/message is forwarded in the response); this error means the result count was unexpected.

Source

Thrown at web/src/pages/api/public/spans.ts:53

      if (!event.body.id) {
        event.body.id = v4();
      }
      const result = await processEventBatch([event], auth, {
        attribution: createIngestionAttribution({
          headers: req.headers,
          authCheck: auth,
        }),
      });
      if (result.errors.length > 0) {
        const error = result.errors[0];
        res
          .status(error.status)
          .json({ message: error.error ?? error.message });
        return { id: "" }; // dummy return
      }
      if (result.successes.length !== 1) {
        logger.error("Failed to create span", { result });
        throw new Error("Failed to create span");
      }
      return { id: event.body.id };
    },
  }),
  PATCH: createAuthedProjectAPIRoute({
    name: "Update Span (Legacy)",
    bodySchema: PatchSpansV1Body,
    responseSchema: PatchSpansV1Response,
    rejectInEventsOnlyMode: true,
    fn: async ({ body, auth, req, res }) => {
      const event = {
        id: v4(),
        type: eventTypes.OBSERVATION_UPDATE,
        timestamp: new Date().toISOString(),
        body: {
          ...body,
          id: body.spanId,
          type: "SPAN",

View on GitHub (pinned to 59d92c7cf3)

Solutions

1. Inspect server logs for the 'Failed to create span' result details
2. Validate span body fields (id, traceId, name, timestamps ISO-8601) before sending
3. Verify trace exists and infrastructure (ClickHouse/Redis) is healthy in self-hosted setups

const spanBodyOk = (b: any) =>
  typeof b.id === 'string' && b.id.length > 0 &&
  typeof b.traceId === 'string' && b.traceId.length > 0 &&
  typeof b.name === 'string' &&
  (b.startTime == null || !Number.isNaN(Date.parse(b.startTime)));

catch (e) { if (/Failed to create span/.test(e?.message ?? '')) { await backoffRetry(sendSpan, 3); } }

When it happens

Trigger: POST /api/public/spans with a body that passes route validation but fails inside the ingestion pipeline, or when internal infrastructure (ClickHouse, queues) rejects the write; server logs contain 'Failed to create span' with the result.

Common situations: Invalid traceId referencing a nonexistent trace in some validation paths; self-hosted instances with ClickHouse/Redis issues; payload edge cases like huge input/output JSON.

Related errors

• Failed to update span
• Failed to create score
• Invalid regex syntax: ${e instanceof Error ? e.message : Str
• Unknown event type: ${eventType}
• Missing project ID

AI-assisted analysis of langfuse/langfuse@59d92c7cf3 (2026-08-27). Data as JSON: /api/errors/2f0183a8581767dc. Report an issue: GitHub.