Flowise Troubleshooting Guide: Flows, Queues & API Errors

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. 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.

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:

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.

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.

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:

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.

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:

Copy it with:

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:

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 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:

Common causes and fixes:

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.

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:

Then, back it up outside the container:

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.

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.

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.

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

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:

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

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.

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:

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

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:

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 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:

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:

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:

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:

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:

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.

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:

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

Or in Docker Compose:

For a long-term fix, follow these steps:

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

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.

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.

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.