Skip to main content
This guide helps you migrate between major versions of Flowise. Major version upgrades may include breaking changes that require updates to your configuration, chatflows, or deployment.
Always backup your database and chatflows before upgrading to a new major version.

​
Pre-Migration Checklist

Before upgrading, complete these steps:
1

Backup Your Database

SQLite:
cp ~/.flowise/database.sqlite ~/backups/database-$(date +%Y%m%d).sqlite
PostgreSQL:
pg_dump -U flowise flowise > ~/backups/flowise-$(date +%Y%m%d).sql
MySQL:
mysqldump -u flowise -p flowise > ~/backups/flowise-$(date +%Y%m%d).sql
2

Export Chatflows

Export all chatflows as JSON from the Flowise UI:
  1. Open each chatflow
  2. Click the export button
  3. Save JSON files to a safe location
3

Document Environment Variables

Save your current .env configuration:
cp packages/server/.env ~/backups/env-backup-$(date +%Y%m%d)
4

Review Release Notes

Read the release notes for breaking changes and new features.
5

Test in Development

If possible, test the upgrade in a development environment first.

​
General Upgrade Process

​
NPM Installation

1

Stop Flowise

Stop the running Flowise instance.
2

Update Package

npm update -g flowise
3

Verify Version

npx flowise --version
4

Start Flowise

npx flowise start
Database migrations will run automatically on first start.
5

Verify Functionality

  • Test existing chatflows
  • Verify API credentials
  • Check custom components

​
Docker Installation

1

Stop Container

docker stop flowise
2

Pull Latest Image

docker pull flowiseai/flowise:latest
3

Remove Old Container

docker rm flowise
4

Start New Container

docker run -d \
  -p 3000:3000 \
  -v flowise_data:/root/.flowise \
  --name flowise \
  flowiseai/flowise
Make sure to preserve your volume mounts and environment variables.

​
From Source

1

Stop Development Server

Stop any running Flowise processes.
2

Update Repository

cd Flowise
git fetch origin
git checkout main
git pull origin main
3

Clean and Reinstall

pnpm clean
pnpm install
4

Rebuild

pnpm build
5

Start Flowise

pnpm start

​
Version-Specific Migrations

Detailed migration guides for specific version upgrades will be added here as major versions are released.

​
Migrating to v3.x

Flowise v3.x is the current major version. If you’re upgrading from v2.x or earlier:
  • Automatic migrations run on first startup
  • No manual intervention typically required
  • Review logs for migration errors
If migration fails:
# Check logs for errors
LOG_LEVEL=debug npx flowise start
Review new environment variables:
  • Check the Environment Variables documentation
  • Update your .env file with new options
  • Remove deprecated variables
  • Some components may have new required fields
  • Custom components may need updates
  • Test all chatflows after upgrade

​
Common Migration Issues

​
Database Migration Failures

Problem: Database migration fails on startup. Solutions:
  1. Check database permissions: 
    # SQLite
chmod 644 ~/.flowise/database.sqlite

# PostgreSQL/MySQL
# Ensure user has ALTER TABLE permissions
  2. Review migration logs: 
    LOG_LEVEL=debug npx flowise start
  3. Manual migration (advanced): 
    # If automatic migration fails, contact support
# Don't manually edit the database without guidance

​
Chatflow Compatibility Issues

Problem: Existing chatflows don’t work after upgrade. Solutions:
  1. Check component versions: Some components may have breaking changes
  2. Review deprecated features: Replace with recommended alternatives
  3. Re-configure nodes: Some nodes may require reconfiguration
  4. Import from backup: If needed, restore from JSON export

​
Custom Component Issues

Problem: Custom components stop working after upgrade. Solutions:
  1. Update component interface: Check if the component API changed
  2. Rebuild components: 
    pnpm build
  3. Review component documentation: Check for breaking changes
  4. Update dependencies: Ensure compatibility with new version

​
Rolling Back

If you need to rollback to a previous version:

​
NPM Installation

# Install specific version
npm install -g [email protected]

# Restore database backup
cp ~/backups/database-backup.sqlite ~/.flowise/database.sqlite

# Start Flowise
npx flowise start

​
Docker Installation

# Use specific version tag
docker pull flowiseai/flowise:2.x.x

docker run -d \
  -p 3000:3000 \
  -v flowise_data:/root/.flowise \
  --name flowise \
  flowiseai/flowise:2.x.x

​
From Source

cd Flowise
git checkout v2.x.x
pnpm clean
pnpm install
pnpm build
pnpm start
Rolling back may require restoring database backups. Database schemas from newer versions may not be compatible with older Flowise versions.

​
Migration Best Practices

Test First

Always test upgrades in a development or staging environment before production

Backup Everything

Backup databases, chatflows, and environment configuration

Read Release Notes

Review all release notes between your current and target version

Plan Downtime

Schedule upgrades during low-traffic periods with planned downtime

​
Post-Migration Verification

After upgrading, verify:
1

Application Starts

Flowise starts without errors
2

Database Connectivity

Database connection is established
3

Chatflows Load

All chatflows appear in the UI
4

Components Available

All required components are visible
5

API Credentials

Saved credentials are accessible
6

Test Execution

Run test queries through your chatflows
7

Custom Components

Verify custom components work correctly

​
Getting Help with Migration

Migration Issues

Get help on Discord for migration problems

GitHub Discussions

Search or ask about migration issues

Release Notes

Review detailed release notes

Changelog

View version history and changes

​
Professional Migration Support

Need help with enterprise migrations?
For enterprise deployments requiring migration assistance, consider Flowise Cloud which includes managed upgrades and professional support.

Build docs developers (and LLMs) love

Get started for freeTalk to us