Skip to content

Troubleshooting and FAQ

Start with the services’ state and their last log lines; most problems name themselves there.

Terminal window
cd /srv/flux
dc() { docker compose --env-file docker/release.env --env-file docker/.env -p "$(sed -n 's/^FLUX_PROJECT=//p' docker/.env)" -f docker/compose.yaml "$@"; }
dc ps -a
dc logs --tail 50 migrate api worker keyring

docker/release.env gives Compose the release’s image names, as ./flux does. A developer’s source checkout uses --env-file docker/.env -f docker/compose.source.yaml instead.

What you see Cause and fix
FLUX_PUBLIC_ORIGIN must use https unless it is a loopback address … The API refuses a plain http origin on a real host name. Use https://… behind a reverse proxy, or http://127.0.0.1:<port> for a local trial.
FLUX_PUBLIC_ORIGIN must be an origin without path, query or credentials Remove any path or trailing segment: https://flux.example.org, not https://example.org/flux. Flux must have its own host name or port.
Another … must be … line naming a variable A value is out of range; the line names it and the accepted values. The configuration reference lists them all.
Set POSTGRES_PASSWORD …, Set FLUX_AUTH_SECRET …, Set FLUX_PUBLIC_ORIGIN … Compose stops before anything starts: fill in the required value in the settings file.
Bind for 127.0.0.1:8081 failed: port is already allocated Another program uses the port. Set another FLUX_PORT in the settings file (on the first run: FLUX_PORT=8090 ./flux up) and point the proxy at it.
can't set healthcheck.start_interval as feature require Docker Engine v25 or later (or ./flux: Docker Engine 25 or newer is required) The Docker Engine is older than 25 and docker compose up creates nothing. Update it: Docker Engine install (docker version shows the server version). Flux needs Engine 25 or newer, see the requirements.
migrate exits 1 with FLUX_V01_DATABASE This database was written by Flux v0.1 (schema 2). Flux v0.2 does not upgrade it … (or ./flux upgrade prints the same and “Your data is as it was”) The volumes hold a v0.1 database. v0.1 had no users, so v0.2 converts nothing and refuses it before any migration runs. Install v0.2 fresh in a new folder with its own FLUX_PROJECT, or after ./flux reset; to go on with v0.1, check out its v0.1.0 files and run ./flux up. What happens and what to do.
all predefined address pools have been fully subnetted Docker ran out of networks on a shared host; see Docker address pools.
Compose project … belongs to another checkout The settings file names a project another checkout created, often a copied .env. Set a different FLUX_PROJECT, or pass --force-project if you really mean that project.
migrate exited with an error, api waits Read dc logs migrate. A ledger mismatch means the database belongs to another version: see migration ledger mismatch and restore the matching backup rather than editing the ledger.
migrate exits 1 after about 5 s with Error: Query read timeout, api and worker never start (v0.1.0, a fresh database on a slow host) v0.1.0 gave the migrator the 2 s request timeout, and its first migration takes longer on a slow disk or CPU (#846). Fixed in the next release. On v0.1.0, apply the baseline by hand: Install, the first migration on a slow host.
A service (api, worker, keyring or db) restarts with exit code 137, or docker inspect shows OOMKilled It hit its memory limit. Raise FLUX_API_MEMORY (or FLUX_WORKER_MEMORY, FLUX_KEYRING_MEMORY; FLUX_DB_MEMORY when db is the one killed) and run ./flux up.
/api/v1/health answers 503 Its warning in dc logs api says which check failed: migrations, the queue schema, or writing to the files volume (disk full or permissions).
What you see Cause and fix
Sign-in or every change fails with 403 ORIGIN_REJECTED The browser’s address is not exactly FLUX_PUBLIC_ORIGIN: another host name, http instead of https, or a missing port. Open the configured address, or correct the setting.
Live updates do not arrive; the stream reconnects The proxy does not pass WebSocket upgrades, or closes idle connections sooner than 25 seconds. See other proxies.
Uploads fail with 413 from the proxy Raise the proxy’s body limit to at least 5 MiB, and to at least FLUX_VIDEO_MAX_MIB if people send videos (nginx: client_max_body_size).
A video plays but cannot seek, or starts only after it has loaded in full The proxy or a CDN strips Range requests or buffers the whole answer. Let Range and 206 Partial Content through for /api/v1/files/ (other proxies).
“This browser can’t play this video” Flux plays what the browser plays natively and never converts a file. The video’s codec (for example HEVC or a rare audio format) is one this browser lacks; Download opens it in a player, and sending it as H.264/AAC in an MP4 plays everywhere.
Every session shows the same address, the proxy’s With the built-in proxy, run ./flux up (it restarts the API with Caddy’s current address). With your own, set FLUX_TRUSTED_PROXIES to the proxy’s measured address (how).
./flux up fails with Bind for 0.0.0.0:80 failed: port is already allocated (or 443) Another proxy holds the port. Stop it and let the built-in HTTPS take over, or keep it and set FLUX_TRUSTED_PROXIES to its address (your own proxy).
The reset page says password reset is unavailable No email configured: an owner or admin makes the person a reset link in Settings › Company, ./flux reset-link <email> prints one for any account (the owner’s too), or set FLUX_SMTP_URL and FLUX_MAIL_FROM.
A reset link says it no longer works It works once and for FLUX_PASSWORD_RESET_TTL_SECONDS (one hour); a newer link for the same account stops it. Make a new one.
Sign-in answers 429 “Too many sign-in attempts for this account. Try again in a few minutes” The account’s own back-off: five wrong passwords in a row make the account wait 30 seconds, then 1, 2, 4 and 8 minutes, and at most 15 minutes. It counts every API process together and does not depend on the client address. A browser that has signed in to the account before carries a signed flux.device cookie and is not held by other people’s guesses (it waits only for its own five wrong passwords); a new device or a browser with cleared cookies waits, even with the right password. The person can wait, or use Forgot password: a reset clears the wait, and the browser that finishes it is remembered (a reset and “Sign out all other devices” also end every older copy of the cookie). Answers do not carry Retry-After on purpose. A 429 that says “Too many attempts in a short time” is the separate per-address limit and clears in a minute.
Sign-up says “That password is too easy to guess” Passwords need at least 12 characters and must not be a common password or built from the person’s name or email. A short phrase of unrelated words works.
New people cannot create an account Accounts come only from a link (#1471): send them an invite link from Settings › Company (the sign-up page without one says to ask for it). A link that was used, revoked or expired, or one for another address, makes no account.
Nobody can create the first account The owner’s account comes from the setup link ./flux up prints while no company exists. “This setup link doesn’t work”: open the whole link; the API log says so at start when FLUX_SETUP_TOKEN is not set.
Feature Check
Push notifications An https FLUX_PUBLIC_ORIGIN, both FLUX_VAPID_PUBLIC_KEY and FLUX_VAPID_PRIVATE_KEY set (the contact FLUX_VAPID_SUBJECT is optional), outbound HTTPS to the push services (push).
Installing on a phone HTTPS at the root of its own origin; iPhone and iPad install from Safari’s Share menu.
Agents answering in Flux (API keys) FLUX_PERSONAL_RUNS=on and a readable FLUX_BACKGROUND_KEY_HOST_FILE. Also the agent runtime with pi in FLUX_AGENT_RUNTIME (every agent runs in the runtime, #1441). The space’s AI must be on, and the person must not be a guest. Settings › AI says “AI is off on this server” while neither this nor the runtime below is on.
Sign-in with Claude or ChatGPT subscriptions FLUX_AGENT_RUNTIME set and applied with ./flux up; ./flux runtime status (agent runtime). A host with Yama ptrace_scope 0 stops the runtime with one message and the fix. Agents beyond what the server’s memory allows wait with “Waiting for room on the server” (FLUX_RUNTIME_MAX_RUNS).
Agents do not search or read the web FLUX_WEB_READS=off turns both off. On, the server needs outbound HTTPS; an agent reads only an address it was given and never one that carries private Flux text.
An MCP client on another computer It needs an https origin; http://127.0.0.1 works only on the server itself. The server also needs outbound HTTPS to fetch the client’s metadata.
Encrypted spaces stay locked Normal after a restart until one of the space’s admins unlocks. If unlocking fails with a swap message, see swap and memory.
Live calls GET /api/v1/live-sessions/capabilities says configured only with the live-media overlay.

The first migration on a slow host (v0.1.0)

Section titled “The first migration on a slow host (v0.1.0)”

Only v0.1.0, only on a fresh, empty database. migrate applies each migration file as one statement, and v0.1.0 gave it the API’s 2 s timeout, so a host where the first file (the whole v0.1 schema) takes longer than 2 s rolls it back on every start. v0.2 gives the migrator its own long bound, so only v0.1.0 has this problem (and v0.1.0 cannot be upgraded to v0.2). To get past it on v0.1.0, apply that file the way migrate does, in one transaction, then start again (migrate then applies the second file and sets up the job queue itself). Run it in the directory of your compose.yaml; IMG is the image value of the release’s release.json, and flux-db-1 is your database container (see docker compose ps):

Terminal window
IMG=<the "image" value from the release's release.json>
docker run --rm --entrypoint cat "$IMG" /app/packages/db/migrations/0001_v0_1_baseline.sql \
| docker exec -i flux-db-1 sh -c 'cat > /tmp/0001.sql'
docker exec flux-db-1 psql -q -v ON_ERROR_STOP=1 -U flux -d flux --single-transaction \
-f /tmp/0001.sql -c "INSERT INTO public.flux_schema_version(version) VALUES (1) ON CONFLICT DO NOTHING"
docker exec flux-db-1 rm -f /tmp/0001.sql
docker compose --env-file .env -f compose.yaml up -d --wait

The migrate log then reads Applied migration 0002_first_time_user.sql and Flux schema 2 and pg-boss ready.

Every Compose network takes one subnet from the Docker daemon’s address pools, and a stock daemon has about 31 (15 /16 networks in 172.17.0.0/12 and 16 /20 networks in 192.168.0.0/16). A Flux project uses 2 networks (default and the internal keyring); with the agent runtime on it uses 7 (the runtime’s control, API, install, egress and own networks).

When the pools are gone, ./flux up stops with Compose’s line all predefined address pools have been fully subnetted and then explains it. One instance on its own machine does not reach that; a shared host, a CI runner or a server with several instances (staging and production, one per team) can: stock pools hold about 14 Flux projects, or 2 with the agent runtime on.

  • Stop projects you no longer need: docker network ls shows the networks per project, docker compose -p <project> down (or ./flux down in that checkout) removes them. ./flux up with the runtime off also removes this project’s runtime networks once nothing uses them.

  • Or give the daemon smaller subnets. In /etc/docker/daemon.json (Docker Desktop: Settings, Docker Engine):

    {
    "default-address-pools": [
    { "base": "172.17.0.0/12", "size": 24 },
    { "base": "192.168.0.0/16", "size": 24 }
    ]
    }

    then restart the daemon (sudo systemctl restart docker; it restarts running containers). That gives 4352 networks of 254 addresses each, plenty for a Flux project. Existing networks keep their subnets until they are recreated. Pick bases that do not overlap your LAN or VPN routes. (dockerd reference, read 2026-10-30.)

Is there an admin panel for the whole server? No. Flux has no server-wide administrator account. Each space has owners and admins who manage its people and settings in the app (administration); the operator manages the server through the settings file and ./flux.

How do I reset a forgotten password without email? Configure email and use Forgot password. Flux has no command that sets a password.

Can I run Flux under a path, such as https://example.org/flux? No. Flux needs its own origin: a host name, or a host name and port.

Can I use an external PostgreSQL? Not with the shipped Compose files: every service builds its database URL from the bundled db. It is not a tested setup.

docker compose prints mount of type volume should not define bind option. Is something misconfigured? No. The files volume is mounted with :z, which tells SELinux hosts (Fedora, RHEL) to give the volume a label that API, worker and the backup helper can all use; without it a container can be denied access to the uploads. Compose 5 calls that option a bind-mount option and warns once per service, but still applies it. ./flux hides the line; keep the option.

Where is my data? In two Docker volumes named after the project, <FLUX_PROJECT>_pgdata (PostgreSQL) and <FLUX_PROJECT>_files (uploads), plus the settings file. ./flux backup captures all three.

Does Flux send anything to its developers? No. Flux itself has no telemetry. Outbound connections are the ones you enable: email, push services, AI providers people connect, link cards, GitHub, and MCP client metadata. The optional agent runtime runs the vendors’ own CLIs, whose egress it limits to their documented hosts.

How do I move to another server? ./flux backup on the old one, copy the archive, then ./flux restore in a fresh checkout on the new one (restore on a fresh machine). Update DNS and FLUX_PUBLIC_ORIGIN if the address changes.

How do I remove Flux? ./flux down stops it and keeps the data. ./flux reset deletes this checkout’s data volumes after confirmation, and ./flux clean also removes the images it built.