{"record":{"id":"2f0183a8581767dc","repo":"langfuse/langfuse","slug":"failed-to-create-span","errorCode":null,"errorMessage":"Failed to create span","messagePattern":"Failed to create span","errorType":"exception","errorClass":"Error","httpStatus":500,"severity":"error","filePath":"web/src/pages/api/public/spans.ts","lineNumber":53,"sourceCode":"      if (!event.body.id) {\n        event.body.id = v4();\n      }\n      const result = await processEventBatch([event], auth, {\n        attribution: createIngestionAttribution({\n          headers: req.headers,\n          authCheck: auth,\n        }),\n      });\n      if (result.errors.length > 0) {\n        const error = result.errors[0];\n        res\n          .status(error.status)\n          .json({ message: error.error ?? error.message });\n        return { id: \"\" }; // dummy return\n      }\n      if (result.successes.length !== 1) {\n        logger.error(\"Failed to create span\", { result });\n        throw new Error(\"Failed to create span\");\n      }\n      return { id: event.body.id };\n    },\n  }),\n  PATCH: createAuthedProjectAPIRoute({\n    name: \"Update Span (Legacy)\",\n    bodySchema: PatchSpansV1Body,\n    responseSchema: PatchSpansV1Response,\n    rejectInEventsOnlyMode: true,\n    fn: async ({ body, auth, req, res }) => {\n      const event = {\n        id: v4(),\n        type: eventTypes.OBSERVATION_UPDATE,\n        timestamp: new Date().toISOString(),\n        body: {\n          ...body,\n          id: body.spanId,\n          type: \"SPAN\",","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/langfuse/langfuse/blob/59d92c7cf365150d10b753b5a0d1708902a2ed60/web/src/pages/api/public/spans.ts#L35-L71","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect server logs for the 'Failed to create span' result details","Validate span body fields (id, traceId, name, timestamps ISO-8601) before sending","Verify trace exists and infrastructure (ClickHouse/Redis) is healthy in self-hosted setups"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"const spanBodyOk = (b: any) =>\n  typeof b.id === 'string' && b.id.length > 0 &&\n  typeof b.traceId === 'string' && b.traceId.length > 0 &&\n  typeof b.name === 'string' &&\n  (b.startTime == null || !Number.isNaN(Date.parse(b.startTime)));","typeGuard":null,"tryCatchPattern":"catch (e) { if (/Failed to create span/.test(e?.message ?? '')) { await backoffRetry(sendSpan, 3); } }","preventionTips":["Send spans via the official SDK ingestion endpoints (batched /api/public/ingestion) rather than single POSTs when throughput matters","Validate ISO-8601 timestamps client-side","Retry with backoff and idempotent span ids"],"tags":["ingestion","spans","internal-server-error"],"backgroundTag":"ingestion-write-failed","analyzedSha":"59d92c7cf365150d10b753b5a0d1708902a2ed60","analyzedAt":"2026-08-27T22:22:00.402Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}