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 Getting Started.

PostgreSQL Version Requirements

LobeHub 2.0 recommends using PostgreSQL 17 or higher.

LobeHub 2.0 introduced the pg_search extension for full-text search. When 2.0 shipped, Neon provided it to new PostgreSQL 17 projects. Neon has since stopped offering pg_search to new projects and has notified affected existing customers that the extension will be removed on September 21, 2026. Existing Neon deployments should complete Migrate from pg_search to Elasticsearch. See Full-Text Search before choosing the search backend for a current deployment.

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