Flowise is a powerful low-code platform for building LLM chains and agents, but self-hosted instances break in predictable ways, such as flows vanish after a redeploy, credentials stop decrypting after a key change, workers silently stop pulling jobs, and the API throws 401 errors that have nothing to do with a wrong key. This Flowise troubleshooting guide walks through every one of these failure modes and recovery steps that protect your data.

If you haven’t deployed Flowise yet, you can start with our step-by-step Flowise Docker Compose setup guide before working through the fixes below.

Why Flowise Troubleshooting Starts With Persistence

Most serious Flowise issues depend on where your data is stored. Flowise stores flows, credentials, chat history, and API keys in a database with a few files on disk, including encryption.key for credentials, .flowise for SQLite, and an optional blob storage folder for uploads.

If Flowise saves these inside the container instead of on a mounted volume, they disappear as soon as the container restarts or is rebuilt. This is the most common reason people report “my flows disappeared”, and knowing this makes every other fix in this Flowise troubleshooting guide easier to understand.

Before you change anything, check where your Flowise install actually saves its data. This one check alone solves a lot of Flowise troubleshooting cases:

docker inspect flowise --format '{{ json .Mounts }}' | python3 -m json.tool
docker exec -it flowise env | grep -E "DATABASE_PATH|SECRETKEY_PATH|APIKEY_PATH|BLOB_STORAGE_PATH"

If Mounts shows nothing, or those paths aren’t linked to a folder on your host machine, none of your data is being saved; fix this first before anything else.

Missing or Non-Persistent Flows

Flows disappearing after a restart, redeploy, or platform update is a storage-mapping problem, not a Flowise bug, and it is the starting point for most Flowise troubleshooting cases.

Confirm the database location

By default, Flowise stores its database in a folder called .flowise inside the container. In Docker Compose, that path must be bind-mounted to the host:

services:
  flowise:
    image: flowiseai/flowise
    restart: always
    environment:
      - PORT=3000
      - DATABASE_PATH=/root/.flowise
      - APIKEY_PATH=/root/.flowise
      - SECRETKEY_PATH=/root/.flowise
      - LOG_PATH=/root/.flowise/logs
      - BLOB_STORAGE_PATH=/root/.flowise/storage
    ports:
      - "3000:3000"
    volumes:
      - ~/.flowise:/root/.flowise

Without that final volumes: line, every path above lives inside the container and is destroyed with it. This is the most frequent root cause in Flowise troubleshooting cases.

Recover data safely

If flows are missing, do not delete or recreate the container yet. Find and check an old (even stopped) Flowise container so you can recover its data before deleting it:

docker ps -a | grep flowise
docker inspect <old_container_id> --format '{{ json .GraphDriver.Data }}'

Copy it with:

docker cp <old_container_id>:/root/.flowise/database.sqlite ./database-backup.sqlite

Once your backup is safe, switch to Postgres for anything beyond local testing. It handles container restarts and multiple workers much better than default SQLite:

environment:
  - DATABASE_TYPE=postgres
  - DATABASE_HOST=postgres
  - DATABASE_PORT=5432
  - DATABASE_NAME=flowise
  - DATABASE_USER=flowise
  - DATABASE_PASSWORD=change-me

Tips to consider:

• Always mount DATABASE_PATH, SECRETKEY_PATH, APIKEY_PATH, and BLOB_STORAGE_PATH to host volumes.
• Export flows regularly as a JSON backup independent of the database.
• Run automated pg_dump snapshots if you’re on Postgres.
• Use a fixed Flowise version number instead of the latest, so an unexpected update doesn’t change your database structure while restarting.

Database Problems and Connection Errors

Database errors usually show up as one of three symptoms, including the app won’t start, saves silently fail, or the chat history is empty despite active flows. This is a common issue in Flowise troubleshooting, which is worth checking first.

Whenever you have a database issue, start by checking the logs:

docker compose logs -f flowise | grep -i -E "database|sqlite|postgres|ECONNREFUSED"

Common causes and fixes:

Symptom	Cause	Fix
SQLITE_BUSY errors	Multiple processes writing to the same SQLite file	Move to Postgres for queue mode
ECONNREFUSED on Postgres	DATABASE_HOST not resolvable from inside the container	Use the Docker Compose service name, not localhost
Migrations fail on startup	Version jump skipped intermediate schema migrations	Upgrade one minor version at a time, checking release notes
Chat history empty	Separate chatmessage table disappeared by a manual DB edit	Restore from your latest pg_dump/SQLite backup

Note: Always take a backup before running a version upgrade. Flowise runs TypeORM migrations automatically on boot, and a failed migration on an unbacked-up SQLite file is unrecoverable without a snapshot.

Encrypted Credentials After Key Changes

This is one of the most damaging issues covered in this Flowise troubleshooting guide because it looks like data loss but is really a decryption mismatch.

Flowise encrypts every stored credential, such as OpenAI keys, Pinecone keys, database passwords inside nodes, etc., using a local encryption.key file or a FLOWISE_SECRETKEY_OVERWRITE passphrase. If that key is regenerated, lost, or mismatched between environments, every existing credential becomes unreadable. You will see errors like “Credentials could not be decrypted” when opening a flow.

You must locate and protect the key immediately, because credential recovery is one of the essential parts of Flowise troubleshooting:

find / -iname "encryption.key" 2>/dev/null
cat /root/.flowise/encryption.key

Then, back it up outside the container:

docker cp flowise:/root/.flowise/encryption.key ./encryption.key.backup

Note: If the key was already lost or rotated, there is no way to decrypt the old credential values. You must recreate the credentials from scratch inside the UI, then re-save every affected node.

To prevent this from happening again:

• Point SECRETKEY_PATH to a mounted folder, so the key doesn’t get deleted when the container restarts.
• Or, set your own fixed passphrase using FLOWISE_SECRETKEY_OVERWRITE=your-passphrase in .env. This way you don’t rely on a generated file; you can restore it anywhere.
• Save a copy of encryption.key or your passphrase somewhere safe, like a password manager, not just on the VPS.
• Don’t change the key while credentials are still using the old one. Move your credentials over first, then rotate the key.

Worker and Queue Failures

Flowise’s queue mode (MODE=queue) splits work between a main server and one or more worker containers coordinated through Redis/BullMQ, and it introduces a whole extra layer of Flowise troubleshooting on its own.

When workers stop picking up jobs, predictions queue forever and API calls time out even though the main server looks healthy.

Diagnose the queue

docker compose logs -f flowise-worker
redis-cli -h <redis-host> -p 6379 llen bull:prediction:wait
redis-cli -h <redis-host> -p 6379 ping

If Redis responds but the queue length keeps growing, the worker isn’t consuming jobs. If Redis itself is unreachable, fix connectivity first; nothing downstream matters until that’s solved.

Fix common worker issues

1. Worker never starts: many Compose templates leave the worker command unset. Force it explicitly:

flowise-worker:
  image: flowiseai/flowise
  command: sh -c "sleep 3 && flowise worker"
  environment:
    - MODE=queue
    - REDIS_HOST=redis
    - REDIS_PORT=6379
    - QUEUE_NAME=flowise-queue

2. Env var mismatch: MODE, REDIS_HOST, REDIS_PORT, QUEUE_NAME, and any Redis auth/TLS settings must be identical on both the main container and every worker. A single missing variable on the worker leaves it idle.

3. Redis filling up over time: unacknowledged jobs accumulate if a worker crashes mid-job. Set a job TTL and enable removeOnComplete/removeOnFail in your queue config, and restart the main service to clear stuck locks:

docker compose restart flowise flowise-worker

4. Scale workers horizontally once a single worker can’t keep up:

docker compose up -d --scale flowise-worker=3

This comes up often in Flowise troubleshooting discussions because queue mode requires more monitoring than the default setup. Keep an eye on Redis regularly; don’t just set it up and forget about it.

API Authentication and 401 Errors

A 401 on every API call means FLOWISE_APIKEY is unset, empty, or malformed, not that your integration code is wrong, and it’s one of the fastest Flowise troubleshooting wins once you isolate the layer.

Check and fix your Flowise API key, then restart the app:

grep FLOWISE_APIKEY .env
echo "FLOWISE_APIKEY=$(openssl rand -hex 32)" >> .env
docker compose down && docker compose up -d

Test directly with the container, bypassing any proxy, to isolate the layer causing the failure:

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $(grep FLOWISE_APIKEY .env | cut -d '=' -f2)" \
  http://localhost:3000/api/v1/prediction/<your-chatflow-id>

If this works but requests through your actual domain don’t, your reverse proxy is removing the Authorization header. See the proxy section below in Flowise troubleshooting to fix this.

Add this to your Nginx location block:

proxy_set_header Authorization $http_authorization;

Other 401 causes to check:

• 401 errors from a specific node, such as OpenAI or Pinecone, usually mean the provider’s key is outdated, not your Flowise API key. Just re-enter the correct key in that node.
• Invisible extra characters: a hidden space or line break in your .env file can break the key without any obvious error. Check for this with: cat -A .env | grep FLOWISE_APIKEY.
• Old browser data: if curl works but the website still shows a 401 error, clear your browser’s storage for that site and refresh the page.

File Upload and WebSocket/Proxy Errors

File upload failures, 403/500 on attachment or document nodes, are permission or path problems on BLOB_STORAGE_PATH, another common Flowise troubleshooting item that gets missed.

Check and fix file permissions for Flowise’s upload storage folder:

docker exec -it flowise ls -la /root/.flowise/storage
docker exec -it flowise chown -R node:node /root/.flowise/storage

Make sure the storage folder can be written to by the container, and check that you have free disk space with df -h. If the disk is full, uploads will fail with an unclear 500 error.

Reverse proxy misconfiguration is the other source of trouble, especially for streaming chat responses that rely on WebSockets/Socket.IO. If the chat UI loads but streaming never starts, your proxy is dropping the Upgrade handshake.

A correct Nginx block looks like this:

server {
    listen 443 ssl;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

The three settings that matter most are proxy_http_version 1.1, Upgrade, and Connection "upgrade".

Note: If you use Nginx Proxy Manager instead of Nginx, just turn on Websockets Support for your proxy host and add the same headers under Advanced. Our Nginx Proxy Manager troubleshooting guide covers more proxy issues, including certificates and headers, that also affect Flowise.

Test your proxy separately from the app itself:

sudo nginx -t
curl -I https://your-domain.com
curl -s -o /dev/null -w "%{http_code}\n" -H "Connection: Upgrade" -H "Upgrade: websocket" https://your-domain.com/socket.io/

Model Timeouts and Slow Predictions

When a chatflow hangs or times out, the bottleneck is never Flowise itself. It is the model call, though it still shows up in Flowise troubleshooting logs as a generic timeout.

Check three things in order:

1. Provider reachability:

curl -I https://api.openai.com

Or ping your local Ollama endpoint from inside the container network, not from your laptop.

2. Rate limits: Getting a lot of 429 errors from the provider looks just like a frozen app in the UI. Check your provider’s dashboard to see if you’re being rate-limited.

3. Proxy timeouts: If your reverse proxy’s proxy_read_timeout is too short, it can cut off a slow but still working model response, making Flowise look stuck. For long agent chains, increase this timeout to at least a few minutes:

proxy_read_timeout 300s;
proxy_send_timeout 300s;

Note: If you’re self-hosting models with Ollama or vLLM, check that your GPU isn’t running out of memory. If it is, the model may fall back to the CPU and become too slow under real load, even if it seemed to work fine in testing.

Memory Crashes and Heap Errors

The following error is common on VPS instances with 1 to 2 GB of RAM, especially when a flow uses heavy nodes like web scrapers, PDF parsers, or large embeddings batches:

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory

For a quick fix, increase Node’s memory limit:

NODE_OPTIONS="--max-old-space-size=4096" npx flowise start

Or in Docker Compose:

environment:
  - NODE_OPTIONS=--max-old-space-size=4096
deploy:
  resources:
    limits:
      memory: 4g

For a long-term fix, follow these steps:

1. Add swap on the VPS as a backup, not as your main memory solution:

sudo fallocate -l 2G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile

2. Process large document imports in smaller batches instead of loading everything at once. For example, crawl only 10 pages at a time.

3. Send heavy ingestion jobs to queue-mode workers so the main API stays fast and responsive.

4. Watch memory use with docker stats or a simple Prometheus/Grafana or Victoria Metrics setup so you notice growth before it causes a crash.

Flowise Deployment Stability Tips

Reactive fixes can only solve so much. The bigger point in this Flowise troubleshooting guide is that flows, credentials, and queue data need the same care as a database. Small config changes, untracked env edits, or upgrades without checking migrations can quickly turn into long recovery jobs.

A few tips that help prevent these problems and save time later include:

• Keep docker-compose.yml and .env.example in version control, and review every change before using it.
• Export chatflows as JSON on a regular schedule, in addition to database backups.
• Use a fixed image tag and test upgrades in staging first.
• Keep your reverse proxy config with the rest of your Flowise setup, not in a separate repo you might forget.

Also, where you run Flowise matters a lot. A Linux VPS with predictable resources is much better than cheap shared hosting, because random CPU throttling and weak storage often cause crashes and missing flows.

Conclusion

Most Flowise failures, such as missing flows, broken credentials, stuck workers, 401 errors, WebSocket issues, and memory crashes, come from the same few causes:

• Missing volumes
• Wrong environment variables
• A reverse proxy that isn’t set up correctly

Go through the fixes in order, back up first, and you’ll solve most issues without losing data. Running Flowise on a stable PerLod VPS with persistent storage and steady memory also helps prevent the next problem.

We hope you enjoy this guide. For more detailed information, you can see the Flowise GitHub repository and issue tracker.

FAQs