Langflow Env Doctor

Diagnosing a local Langflow setup

Run the bundled script first. It checks everything below in order, keeps going after a failure so you see the whole picture, and exits with the number of failures.

# from the directory containing docker-compose.yaml
bash scripts/doctor.sh            # everything
bash scripts/doctor.sh --quick    # skip checks that need the container running

On Windows, run it in Git Bash — the shell that ships with Git for Windows, not PowerShell or cmd. Right-click the folder and choose Git Bash Here. The script reports which platform and which Python it detected in its first section, which is worth reading before anything else.

Read its output before reading the rest of this file. The sections below are the detail behind each check, for when the one-line fix is not enough.

1. docker: command not found — even though Docker Desktop is installed

On macOS, Docker Desktop's binaries are not always added to PATH. They live at /Applications/Docker.app/Contents/Resources/bin. Add that to your shell profile:

export PATH="/Applications/Docker.app/Contents/Resources/bin:$PATH"

On Windows, the installer does add Docker to PATH, but a Git Bash window opened before the install will not see it — reopen the terminal. If Docker Desktop is running and docker is still missing, turn on Settings → Resources → WSL integration.

The tell that this is your problem and not a login problem is an error reading:

docker-credential-desktop: executable file not found in $PATH

That message mentions credentials, so it looks like an authentication failure. It is not. Docker found docker but not the credential helper that sits beside it, which means the whole bundled bin directory is missing from PATH. Every registry operation — pull, build, push — fails until you fix the path. No amount of docker login helps.

2. A pull or build that hangs with no progress at all

Before suspecting the registry or your network, look for an unanswered macOS permission dialog. Docker Desktop asks for Files-and-Folders access, and the prompt can appear behind other windows or on another desktop. While it is pending:

• a pull or build sits at zero bytes indefinitely, and
• docker container start drops the daemon connection with a bare EOF.

A bare EOF with no other detail is the signature. Bring Docker Desktop to the front, answer the dialog, and retry.

Distinguish "hanging" from "slow": a first pull of a multi-gigabyte image is genuinely slow but shows steadily advancing layer progress. No movement for minutes is the hang.

3. .env

cp .env.example .env    # then fill it in

docker-compose.yaml loads the whole file with env_file:, so every variable in it reaches the container, and several are read at import time — which is why they belong in .env and not in a component's fields.

The one that is not optional is EDGAR_IDENTITY. The SEC rejects requests that do not identify the caller, and the client library has no default to fall back on, so leaving it as the placeholder makes every EDGAR action fail. The format is Your Name your.email@domain.com.

A model API key can stay blank until you need a model. Langfuse keys log a "credentials missing" line and trace nothing, which is a warning, not a failure.

4. The container never reaches (healthy)

docker compose up -d
docker compose ps                    # STATUS must reach (healthy); allow ~90s
docker compose logs --tail 50 langflow

(health: starting) for the first minute and a half is normal — the healthcheck polls /health on an interval and the first probes fail while the app boots. Only treat it as broken once it is still not healthy after about two minutes, or if it goes to unhealthy or Exited.

If port 7860 is refused while the container looks healthy, something else may hold the port:

lsof -iTCP:7860 -sTCP:LISTEN

5. A component is missing from the sidebar

Two causes, and they need different fixes.

It was added or edited since the container last started. Langflow loads custom components at process startup. Editing a .py, adding a new file, or adding a whole new category directory has no effect on a running instance, and refreshing the browser does not help — the old class object is still registered.

docker compose restart langflow      # ~30s. NOT a rebuild.

docker compose build is only needed when the Dockerfile changes. Rebuilding to pick up a Python edit wastes several minutes and changes nothing.

It failed to load. The two silent killers are a missing __init__.py in the category directory (loads nothing, logs nothing) and an import that is not a top-level import statement. Check:

docker compose logs langflow | grep -i "could not build template"

Anything printed there is a component that failed. For the fix, use the langflow-component-build skill — that is what it is for.

To see what actually registered, rather than scrolling the sidebar:

TOKEN=$(curl -s --compressed http://localhost:7860/api/v1/auto_login \
        | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')
curl -s --compressed http://localhost:7860/api/v1/all -H "Authorization: Bearer $TOKEN" \
  | python3 -c '
import json, sys
d = json.load(sys.stdin)
for c in sorted(d):
    if c == "component_display_names":
        continue
    own = [k for k in d[c] if k.startswith("ext:") and k.endswith("@extra")]
    if own:
        print(c, own)
'

Custom components appear as ext:<category>:<ClassName>@extra. A key ending @official is a bundle that ships with Langflow, not yours. A category that exists on disk but is missing from this output is the "needs a restart" case above.

6. Things that look like failures and are not

• One OpenAI 400 per model per container process saying function tools with reasoning_effort are not supported. This is by design: Langflow discovers what a model supports by trying, reading the error text, retrying with different settings, and caching the result. It is logged at error level, which is misleading. Ignore it unless it repeats many times within one container run.
• Langfuse credentials missing if you have not set up tracing yet.
• (health: starting) in the first ~90 seconds after up -d.

7. When the answer is not here

For how Langflow itself works — a specific component, an environment variable, the API, MCP, deployment — use the langflow-1-11-docs skill instead of guessing. Environment variable names in particular move between minor versions, and a recalled name that no longer exists fails silently: Langflow ignores unknown variables.