Skip to main content
This page documents all environment variables used by the Vercel AI Chatbot application.

​
Required variables

These environment variables must be set for the application to function properly.

​
AUTH_SECRET

​
AUTH_SECRET
string
required
Secret key used by NextAuth.js to encrypt session tokens and sign cookies.How to generate:
openssl rand -base64 32
Or use the online generator: https://generate-secret.vercel.app/32
Keep this secret secure and never commit it to version control. If exposed, regenerate it immediately and update your deployment.

​
POSTGRES_URL

​
POSTGRES_URL
string
required
PostgreSQL database connection string for storing user data, chats, messages, and documents.Format:
postgres://username:password@host:port/database
On Vercel: Automatically created and added when you provision a Vercel Postgres database.Documentation: https://vercel.com/docs/postgres

​
BLOB_READ_WRITE_TOKEN

​
BLOB_READ_WRITE_TOKEN
string
required
Access token for Vercel Blob storage used to store file uploads and attachments.On Vercel: Automatically created and added when you provision a Vercel Blob store.Documentation: https://vercel.com/docs/vercel-blob

​
REDIS_URL

​
REDIS_URL
string
required
Redis connection string for rate limiting and caching.On Vercel: Automatically created and added when you provision Vercel KV (Redis).Documentation: https://vercel.com/docs/redis

​
AI_GATEWAY_API_KEY

​
AI_GATEWAY_API_KEY
string
API key for accessing Vercel AI Gateway.Required for: Non-Vercel deployments onlyNot required for: Vercel deployments (uses OIDC tokens automatically)How to create:
  1. Visit https://vercel.com/ai-gateway
  2. Create a new API key
  3. Add the key to your environment variables
Documentation: https://vercel.com/ai-gateway
On Vercel deployments, AI Gateway authentication is handled automatically using OIDC tokens. You only need to set AI_GATEWAY_API_KEY for non-Vercel deployments.

​
Setting up environment variables

​
Local development

For local development, create a .env.local file in your project root:
.env.local
# Copy from .env.example and fill in your values
AUTH_SECRET=your-generated-secret-here
POSTGRES_URL=postgres://user:password@localhost:5432/chatbot
BLOB_READ_WRITE_TOKEN=your-blob-token-here
REDIS_URL=redis://localhost:6379
Never commit your .env.local file to version control. It’s already included in .gitignore.

​
Vercel deployment

For Vercel deployments, use the Vercel CLI to manage environment variables:
1

Install Vercel CLI

npm i -g vercel
2

Link your project

vercel link
This creates a .vercel directory with your project configuration.
3

Pull environment variables

vercel env pull
This downloads your Vercel environment variables to .env.local.
Alternatively, set environment variables in the Vercel Dashboard:
  1. Go to your project settings
  2. Navigate to “Environment Variables”
  3. Add each variable with appropriate environment scope (Production, Preview, Development)

​
Other platforms

For other deployment platforms:
  • Docker: Use environment variables in your docker-compose.yml or runtime configuration
  • AWS/GCP/Azure: Use platform-specific secret management (Parameter Store, Secret Manager, Key Vault)
  • Self-hosted: Set environment variables in your process manager (PM2, systemd) or shell profile

​
Environment variable precedence

Next.js loads environment variables in the following order (highest precedence first):
  1. Process environment variables
  2. .env.local
  3. .env.production or .env.development (depending on NODE_ENV)
  4. .env

​
Verifying your configuration

To verify your environment variables are correctly set: 
# Check if required variables are present (without showing values)
node -e "console.log([
  'AUTH_SECRET',
  'POSTGRES_URL',
  'BLOB_READ_WRITE_TOKEN',
  'REDIS_URL'
].map(key => ({ key, set: !!process.env[key] })))"
This will show which variables are set without exposing their values.

​
Security best practices

Follow these security best practices to protect your environment variables:
  • Never commit .env.local or any file containing secrets
  • Use different values for development, preview, and production environments
  • Rotate secrets regularly, especially AUTH_SECRET
  • Use platform-specific secret management when available
  • Limit access to environment variables to essential team members
  • Audit access logs regularly

​
Troubleshooting

If you see authentication errors or session issues:
  1. Verify AUTH_SECRET is set in your environment
  2. Generate a new secret: openssl rand -base64 32
  3. Add it to your .env.local or deployment platform
  4. Restart your application
If you see database connection errors:
  1. Verify POSTGRES_URL is correctly formatted
  2. Check database credentials and network access
  3. Ensure database is running and accessible
  4. Test connection with: psql $POSTGRES_URL
If you see AI Gateway authentication errors:On Vercel: OIDC authentication should work automatically. Check:
  • Your project is properly deployed on Vercel
  • AI Gateway is enabled for your account
Non-Vercel deployments:
If you see file upload or storage errors:
  1. Verify BLOB_READ_WRITE_TOKEN is set
  2. Check token has read and write permissions
  3. Ensure Blob store is provisioned in your Vercel project
  4. Verify token hasn’t expired

​
Next steps

Database setup

Configure PostgreSQL and run migrations

Deploy to Vercel

Deploy your application to production

Build docs developers (and LLMs) love

Get started for freeTalk to us