Guide for migrating your LobeChat deployment from NextAuth authentication to
Better Auth, including simple and full migration options.
tags:
- Authentication Service
- Better Auth
- NextAuth
- Migration
---
# Migrating from NextAuth to Better Auth
This guide helps you migrate your existing NextAuth-based LobeChat deployment to Better Auth.
<Callout type={'info'}>
Better Auth is the recommended authentication solution for LobeChat. It offers simpler configuration, more SSO providers, and better self-hosting support.
</Callout>
<Callout type={'error'}>
**Important Notice**:
- **Always backup your database first!** For Neon users, create a backup via [Fork Branch](https://neon.tech/docs/manage/branches#create-a-branch)
- LobeChat is not responsible for any data loss or issues that may occur during the migration process
- This guide is intended for users with development experience; not recommended for users without technical background
- If you have any questions, feel free to ask in our [Discord](https://discord.com/invite/AYFPHvv2jT) community or [GitHub Issue](https://github.com/lobehub/lobe-chat/issues)
</Callout>
## Choose Your Migration Path
| Method | Best For | User Impact | Data Preserved |
| [Simple Migration](#simple-migration) | Small deployments (≤ 10 users) | Users need to re-login | Chat history, settings |
| [Full Migration](#full-migration) | Large deployments | Seamless for users | Everything including SSO connections |
<Callout type={'info'}>
**Note**: NextAuth never supported email/password login, so there are no password hashes to migrate. The main benefit of full migration is preserving SSO connections (Google, GitHub, etc.).
**Note**: Microsoft Entra ID provider name changed from `microsoft-entra-id` to `microsoft`, and the environment variable prefix changed from `AUTH_MICROSOFT_ENTRA_ID_` to `AUTH_MICROSOFT_`.
</Callout>
### New Feature Variables
Better Auth supports additional features with these new environment variables:
See [Authentication Service Configuration](/docs/self-hosting/advanced/auth) for complete environment variables and SSO provider setup.
</Callout>
2. **Redeploy LobeChat**
Deploy the new version with Better Auth enabled.
3. **Notify Users**
Inform users to log in again with their previous SSO account. Chat history and settings will be preserved since user IDs remain the same.
<Callout type={'tip'}>
This method is quick and requires minimal setup. Users just need to re-login with their existing SSO provider.
</Callout>
## Full Migration
For larger deployments or when you need to preserve SSO connections, use the migration script. This migrates data from the `nextauth_accounts` table to the Better Auth `accounts` table.
<Callout type={'error'}>
**Important Notice**:
- **Always backup your database first!** For Neon users, create a backup via [Fork Branch](https://neon.tech/docs/manage/branches#create-a-branch)
- Migration scripts must be **run locally after cloning the repository**, not in the deployment environment
- Due to the high-risk nature of user data migration, **we do not provide automatic migration during deployment**
- Always use dry-run mode first to verify the script runs successfully before executing
- Always verify in a test environment before operating on production database
</Callout>
### Prerequisites
**Environment Requirements:**
- Node.js 18+
- Git (for cloning the repository)
- pnpm (for installing dependencies)
**Preparation:**
1. Clone the LobeChat repository and install dependencies:
- Change `NEXTAUTH_TO_BETTERAUTH_DRY_RUN` back to `1`
2. Run the script:
```bash
# Run migration (dry-run mode to verify)
npx tsx scripts/nextauth-to-betterauth/index.ts
```
Review the output logs, confirm no issues, then proceed to the next step.
### Step 5: Execute Migration and Verify (Production Environment)
Update `.env` to set `NEXTAUTH_TO_BETTERAUTH_DRY_RUN` to `0`, then execute:
```bash
# Execute migration
npx tsx scripts/nextauth-to-betterauth/index.ts
# Verify the migration
npx tsx scripts/nextauth-to-betterauth/verify.ts
```
### Step 6: Configure Better Auth and Redeploy
After migration is complete, follow [Simple Migration - Step 1](#steps) to configure Better Auth environment variables and redeploy.
<Callout type={'tip'}>
For complete Better Auth configuration, see [Authentication Service Configuration](/docs/self-hosting/advanced/auth), including all supported SSO providers and email service configuration.
