Troubleshooting

This guide covers common issues you might encounter when using Flowise and their solutions. If you don’t find your issue here, check our FAQ or reach out on Discord.

Installation Issues

Port Already in Use

Problem: Flowise won’t start because port 3000 is already in use. Solution:

Change Port
Kill Existing Process

Set a different port using environment variables:

PORT=3001 npx flowise start

Or in your .env file:

PORT=3001

Linux/Mac:

lsof -ti:3000 | xargs kill -9

Windows (PowerShell):

Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process -Force

Windows (CMD):

netstat -ano | findstr :3000
taskkill /PID <PID> /F

JavaScript Heap Out of Memory

Problem: Build fails with “FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory” Solution: Increase Node.js memory allocation:

macOS/Linux/Git Bash
Windows PowerShell
Windows CMD

export NODE_OPTIONS="--max-old-space-size=4096"
pnpm build

$env:NODE_OPTIONS="--max-old-space-size=4096"
pnpm build

set NODE_OPTIONS=--max-old-space-size=4096
pnpm build

PNPM Version Mismatch

Problem: Installation fails with PNPM version errors. Solution: Flowise requires PNPM v10. Install the correct version:

npm i -g pnpm@10
pnpm --version  # Should show 10.x.x

Node.js Version Issues

Problem: Compatibility errors during installation or runtime. Solution: Flowise requires Node.js >= 18.15.0 (< 19.0.0 or ^20):

node --version  # Should show v18.15.0+ or v20.x.x

Consider using nvm to manage Node.js versions:

# Install and use Node.js 20
nvm install 20
nvm use 20

Runtime Issues

Components Not Appearing

Problem: Custom or community components don’t show up in the UI. Solutions:

Enable Community Nodes

Add to your .env file:

SHOW_COMMUNITY_NODES=true

Rebuild Components

After adding custom components:

pnpm build
pnpm start

Clear Cache

Perform a clean rebuild:

pnpm clean
pnpm build
pnpm start

API Credentials Not Saving

Problem: API keys and credentials aren’t persisting after restart. Solutions:

Check encryption key path:

# Verify SECRETKEY_PATH is writable
ls -la ~/.flowise/

Use consistent encryption key:

# In .env file
FLOWISE_SECRETKEY_OVERWRITE=your-secret-key-here

Check database permissions:

# Ensure database file is writable
chmod 644 ~/.flowise/database.sqlite

Database Connection Errors

Problem: Cannot connect to PostgreSQL or MySQL database. Solutions:

PostgreSQL Connection Issues

Verify your environment variables:

DATABASE_TYPE=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=flowise
DATABASE_PASSWORD=your-password
DATABASE_NAME=flowise

Test connection:

psql -h localhost -U flowise -d flowise

For SSL connections:

DATABASE_SSL=true
# Or use base64 encoded certificate
DATABASE_SSL_KEY_BASE64=your-cert-base64

MySQL Connection Issues

Verify configuration:

DATABASE_TYPE=mysql
DATABASE_HOST=localhost
DATABASE_PORT=3306
DATABASE_USER=flowise
DATABASE_PASSWORD=your-password
DATABASE_NAME=flowise

Test connection:

mysql -h localhost -u flowise -p flowise

CORS Errors

Problem: Browser shows CORS errors when accessing Flowise API. Solution: Configure allowed origins:

# Single origin
CORS_ORIGINS=https://yourdomain.com

# Multiple origins (comma-separated)
CORS_ORIGINS=https://domain1.com,https://domain2.com

# Allow all (not recommended for production)
CORS_ORIGINS=*

For iframe embedding:

IFRAME_ORIGINS=https://yourdomain.com

Development Issues

Hot Reload Not Working

Problem: Changes in development mode don’t reload automatically. Solutions:

For UI/Server changes: Should reload automatically with pnpm dev
For component changes: Rebuild required:
```
pnpm build
```
Check .env files exist:
- packages/ui/.env with VITE_PORT
- packages/server/.env with PORT

Module Not Found Errors

Problem: Import errors or missing module errors during development. Solutions:

Clean Installation

pnpm clean
rm -rf node_modules
pnpm install

Rebuild All Packages

pnpm build

Check Package Links

# Verify workspace links
pnpm list

TypeScript Errors

Problem: Type errors during development or build. Solution: Ensure you’re using the correct TypeScript version:

# Should be 5.4.5+ as specified in package.json
npx tsc --version

Regenerate type definitions:

pnpm build

Production Issues

File Upload Failures

Problem: Cannot upload files or attachments. Solutions:

Check file size limit:

FLOWISE_FILE_SIZE_LIMIT=50mb  # Adjust as needed

Verify storage configuration:

Local Storage
S3 Storage
GCS Storage

STORAGE_TYPE=local
BLOB_STORAGE_PATH=/path/to/storage

Ensure path is writable:

mkdir -p /path/to/storage
chmod 755 /path/to/storage

STORAGE_TYPE=s3
S3_STORAGE_BUCKET_NAME=your-bucket
S3_STORAGE_ACCESS_KEY_ID=your-key
S3_STORAGE_SECRET_ACCESS_KEY=your-secret
S3_STORAGE_REGION=us-east-1

STORAGE_TYPE=gcs
GOOGLE_CLOUD_STORAGE_BUCKET_NAME=your-bucket
GOOGLE_CLOUD_STORAGE_PROJ_ID=your-project
GOOGLE_CLOUD_STORAGE_CREDENTIAL=/path/to/credentials.json

Performance Issues

Problem: Slow response times or high memory usage. Solutions:

Optimize Database

Switch to PostgreSQL for better performance:

DATABASE_TYPE=postgres
# ... other database settings

Regular maintenance:

-- PostgreSQL
VACUUM ANALYZE;
REINDEX DATABASE flowise;

Reduce Logging

Lower log verbosity in production:

LOG_LEVEL=error
DEBUG=false

Scale Horizontally

Deploy multiple Flowise instances behind a load balancer. Ensure:

Shared database (PostgreSQL/MySQL)
Shared storage (S3/GCS)
Session affinity if needed

Docker Issues

Problem: Issues running Flowise in Docker. Solutions:

Container Won't Start

Check logs:

docker logs flowise

Ensure proper port mapping:

docker run -d -p 3000:3000 --name flowise flowiseai/flowise

Volume Persistence

Mount volumes for data persistence:

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

Environment Variables

Pass environment variables:

docker run -d \
  -p 3000:3000 \
  -e DATABASE_TYPE=postgres \
  -e DATABASE_HOST=db \
  --name flowise \
  flowiseai/flowise

Or use docker-compose with .env file.

API & Integration Issues

API Authentication Errors

Problem: External API calls failing with authentication errors. Solutions:

Verify API credentials are correctly saved in Flowise
Check API key format (some providers require prefixes like sk-)

Test credentials directly:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Review rate limits on your API provider account

Custom Tool/Function Issues

Problem: Custom tools or functions not working. Solutions:

Enable dependencies:

TOOL_FUNCTION_BUILTIN_DEP=fs,path,crypto
TOOL_FUNCTION_EXTERNAL_DEP=axios,lodash
ALLOW_BUILTIN_DEP=true

Check function syntax in the custom tool editor
Enable debug mode:
```
DEBUG=true
LOG_LEVEL=debug
```

Getting More Help

Before asking for help, collect the following information:

Flowise version (package.json or GitHub release)
Node.js version (node --version)
Operating system
Database type
Error messages and logs
Steps to reproduce

FAQ

Check frequently asked questions

Discord Community

Get real-time help from the community

GitHub Discussions

Search or start a discussion

Report Bug

File a bug report

Enable Debug Logging

For detailed troubleshooting, enable comprehensive logging:

# In .env file or environment
DEBUG=true
LOG_LEVEL=debug
LOG_PATH=/path/to/logs

Then check the logs:

tail -f /path/to/logs/flowise.log

This will provide detailed information about:

Component initialization
API calls and responses
Database queries
Error stack traces
Request/response cycles

Community

Support

Troubleshooting

Installation Issues

Port Already in Use

JavaScript Heap Out of Memory

PNPM Version Mismatch

Node.js Version Issues

Runtime Issues

Components Not Appearing

API Credentials Not Saving

Database Connection Errors

CORS Errors

Development Issues

Hot Reload Not Working

Module Not Found Errors

TypeScript Errors

Production Issues

File Upload Failures

Performance Issues

Docker Issues

API & Integration Issues

API Authentication Errors

Custom Tool/Function Issues

Getting More Help

FAQ

Discord Community

GitHub Discussions

Report Bug

Enable Debug Logging

Build docs developers (and LLMs) love

Community

Support

​Installation Issues

​Port Already in Use

​JavaScript Heap Out of Memory

​PNPM Version Mismatch

​Node.js Version Issues

​Runtime Issues

​Components Not Appearing

​API Credentials Not Saving

​Database Connection Errors

​CORS Errors

​Development Issues

​Hot Reload Not Working

​Module Not Found Errors

​TypeScript Errors

​Production Issues

​File Upload Failures

​Performance Issues

​Docker Issues

​API & Integration Issues

​API Authentication Errors

​Custom Tool/Function Issues

​Getting More Help

FAQ

Discord Community

GitHub Discussions

Report Bug

​Enable Debug Logging

Build docs developers (and LLMs) love

Installation Issues

Port Already in Use

JavaScript Heap Out of Memory

PNPM Version Mismatch

Node.js Version Issues

Runtime Issues

Components Not Appearing

API Credentials Not Saving

Database Connection Errors

CORS Errors

Development Issues

Hot Reload Not Working

Module Not Found Errors

TypeScript Errors

Production Issues

File Upload Failures

Performance Issues

Docker Issues

API & Integration Issues

API Authentication Errors

Custom Tool/Function Issues

Getting More Help

Enable Debug Logging