LobeHub 2.0 Breaking Changes

This document outlines the breaking changes introduced in LobeHub 2.0 and provides migration guidance for users upgrading from version 1.x.

Removed Environment Variables

The following environment variables have been removed in LobeHub 2.0:

Environment Variable	Removal Reason
ACCESS_CODE	No longer supported, use Better Auth authentication system
NEXT_PUBLIC_SERVICE_MODE	2.0 only supports Server DB mode, Client DB (PGlite) removed
NEXT_PUBLIC_ENABLE_BETTER_AUTH	Automatically detected via AUTH_SECRET presence
NEXT_PUBLIC_AUTH_URL / AUTH_URL	Automatically detected from request headers
NEXT_PUBLIC_ENABLE_NEXT_AUTH	NextAuth removed
NEXT_AUTH_SECRET	NextAuth removed
NEXT_AUTH_SSO_PROVIDERS	NextAuth removed
NEXTAUTH_URL	NextAuth removed
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY	Clerk removed
CLERK_SECRET_KEY	Clerk removed

New Required Environment Variables

LobeHub 2.0 only supports Better Auth authentication system. The following environment variables are now required:

• AUTH_SECRET: Used to encrypt session tokens
• JWKS_KEY: Used to sign and verify JWTs, including OIDC JWT tokens and internal service call authentication tokens

New Optional Environment Variables

Environment Variable	Description
AUTH_SSO_PROVIDERS	Comma-separated list of enabled SSO providers
INTERNAL_JWT_EXPIRATION	Internal JWT token expiration time (default: 30s)
AUTH_EMAIL_VERIFICATION	Set to 1 to require email verification
SMTP_HOST	SMTP server hostname for email features
SMTP_PORT	SMTP server port
SMTP_USER	SMTP authentication username
SMTP_PASS	SMTP authentication password

For detailed configuration, see Authentication Environment Variables.

Authentication System Changes

LobeHub 2.0 only supports Better Auth authentication system. NextAuth and Clerk are no longer supported.

Migration Guide

Migrating from NextAuth

See the NextAuth Migration Guide.

Migrating from Clerk

See the Clerk Migration Guide.

Database Mode Changes

LobeHub 2.0 only supports Server DB mode. Client DB (PGlite) is no longer supported. If you were using NEXT_PUBLIC_SERVICE_MODE=client, you need to migrate to Server DB deployment.

For deployment guides, see Server Database Deployment.

PostgreSQL Version Requirements

LobeHub 2.0 recommends using PostgreSQL 17 or higher.

This is because LobeHub 2.0 uses the pg_search extension for full-text search capabilities. If you use Serverless Postgres services like Neon, the pg_search extension is only available on PostgreSQL 17.

If you self-host your database with Docker, we recommend using the paradedb/paradedb:latest-pg17 image.