# Langflow Env Doctor

> Diagnose a broken local Langflow course setup on macOS or Windows - Docker, docker compose, .env, the container, port 7860, or a component that will not load. Use this whenever `docker` is not found, the daemon will not respond, `docker compose up` hangs or exits, the container never reaches (healthy), localhost:7860 refuses to connect or shows an error page, or a pull or build stalls with no progress. Covers these literal errors: "docker-credential-desktop: executable file not found in $PATH", a bare "EOF" from the daemon, and "port is already allocated". Also use it as a first step before debugging anything else about a local Langflow, and after a fresh clone to check the setup is complete.

- Skill: `x1linwang/langflow-env-doctor` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add x1linwang/langflow-env-doctor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/x1linwang/langflow-env-doctor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: x1linwang (https://skillmd.com/u/x1linwang)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/x1linwang/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.

```bash
# 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:

```bash
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`

```bash
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)`

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

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

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

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

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