paperclipai/paperclip · error

BETTER_AUTH_SECRET (or PAPERCLIP_AGENT_JWT_SECRET) must be s

Error message

BETTER_AUTH_SECRET (or PAPERCLIP_AGENT_JWT_SECRET) must be set. For local development, set BETTER_AUTH_SECRET=paperclip-dev-secret in your .env file.

What it means

Startup secret validation when creating the better-auth instance: neither BETTER_AUTH_SECRET nor its fallback PAPERCLIP_AGENT_JWT_SECRET is set. Auth token signing is impossible without a secret; in authenticated deployments this is a hard failure at boot. For local development set BETTER_AUTH_SECRET=paperclip-dev-secret in .env.

Source

Thrown at server/src/auth/better-auth.ts:190

    normalizeWorkspaceHandoffOrigin(env.PAPERCLIP_PUBLIC_URL)
    ?? (config.authBaseUrlMode === "explicit"
      ? normalizeWorkspaceHandoffOrigin(config.authPublicBaseUrl)
      : null);
  return {
    key,
    instanceId: resolvePaperclipInstanceId(),
    executionWorkspaceId: resolveWorkspaceHandoffLocalWorkspaceId(env),
    companyId: resolveWorkspaceHandoffLocalCompanyId(env),
    origin: configuredOrigin,
  };
}

export function createBetterAuthInstance(db: Db, config: Config, trustedOrigins: string[]): BetterAuthInstance {
  const baseUrl = config.authBaseUrlMode === "explicit" ? config.authPublicBaseUrl : undefined;
  const publicUrl = process.env.PAPERCLIP_PUBLIC_URL?.trim() || baseUrl;
  const secret = process.env.BETTER_AUTH_SECRET ?? process.env.PAPERCLIP_AGENT_JWT_SECRET;
  if (!secret) {
    throw new Error(
      "BETTER_AUTH_SECRET (or PAPERCLIP_AGENT_JWT_SECRET) must be set. " +
      "For local development, set BETTER_AUTH_SECRET=paperclip-dev-secret in your .env file.",
    );
  }
  const disableSecureCookies = shouldDisableSecureAuthCookies({
    deploymentMode: config.deploymentMode,
    deploymentExposure: config.deploymentExposure,
    authBaseUrlMode: config.authBaseUrlMode,
    authPublicBaseUrl: config.authPublicBaseUrl,
    publicUrl,
  });

  const authConfig = {
    baseURL: baseUrl,
    secret,
    trustedOrigins,
    database: drizzleAdapter(db, {
      provider: "pg",

View on GitHub (pinned to a7e689b3c3)

Solutions

1. Set BETTER_AUTH_SECRET in your environment (for local dev: BETTER_AUTH_SECRET=paperclip-dev-secret in .env).
2. Alternatively set PAPERCLIP_AGENT_JWT_SECRET.

When it happens

Trigger: Thrown at server/src/auth/better-auth.ts:152 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of paperclipai/paperclip@a7e689b3c3 (2026-08-18). Data as JSON: /api/errors/403b53a292d22001. Report an issue: GitHub.