langfuse/langfuse · error · TRPCError

BAD_REQUEST

BAD_REQUEST

Error message

Missing environment variable: `ENCRYPTION_KEY`. Please consult our docs: https://langfuse.com/self-hosting

What it means

Same missing-ENCRYPTION_KEY guard, but on self-hosted (no cloud region) the error is surfaced honestly as BAD_REQUEST telling the operator to consult self-hosting docs, since storing the PostHog API key requires encryption at rest.

Source

Thrown at web/src/features/posthog-integration/posthog-integration-router.ts:90

        // Drop the base schema default so an omitted value preserves the
        // persisted source instead of rewriting it to the legacy default.
        exportSource: z.enum(AnalyticsIntegrationExportSource).optional(),
      }),
    )
    .mutation(async ({ input, ctx }) => {
      throwIfNoProjectAccess({
        session: ctx.session,
        projectId: input.projectId,
        scope: "integrations:CRUD",
      });
      if (!env.ENCRYPTION_KEY) {
        if (env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION) {
          throw new TRPCError({
            code: "INTERNAL_SERVER_ERROR",
            message: "Internal server error",
          });
        } else {
          throw new TRPCError({
            code: "BAD_REQUEST",
            message:
              "Missing environment variable: `ENCRYPTION_KEY`. Please consult our docs: https://langfuse.com/self-hosting",
          });
        }
      }

      // Validate PostHog hostname to prevent SSRF attacks
      try {
        await validateWebhookURL(input.posthogHostname);
      } catch (error) {
        throw new TRPCError({
          code: "BAD_REQUEST",
          message:
            error instanceof Error
              ? `Invalid PostHog hostname: ${error.message}`
              : "Invalid PostHog hostname",
        });

View on GitHub (pinned to 59d92c7cf3)

Solutions

1. Generate a key (openssl rand -hex 16... per docs) and set ENCRYPTION_KEY in the web container env
2. Restart the web server after setting it

Example fix

# .env
ENCRYPTION_KEY=$(openssl rand -hex 16)  # 32 bytes as required

if (!process.env.ENCRYPTION_KEY) { /* show self-hosting setup instructions before save */ }

catch BAD_REQUEST with 'ENCRYPTION_KEY' in message and link to self-hosting docs

When it happens

Trigger: Self-hosted deployment without ENCRYPTION_KEY configured, attempting to create/update a PostHog integration.

Common situations: Fresh self-hosted installs that skipped ENCRYPTION_KEY in docker-compose/.env.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• INTERNAL_SERVER_ERROR
• File size must be less than ${env.LANGFUSE_S3_MEDIA_MAX_CONT
• PostHog integration not found
• Observations in trace are too large: ${(payloadSize / 1e6).t
• The configured export source reads the enriched events table

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