fluid doctor
Check that the CLI and the machine it runs on are ready (and, with --contract, that one contract's operation can run on it): copilot configuration, the memory store, the tools and Python libraries that individual commands shell out to or import, and the FLUID_* switches that change CLI behaviour.
Syntax
fluid doctor [--scope SCOPE] [--env] [--json] [--features-only] [--strict] [--extended] [--out-dir DIR] [--verbose]
fluid doctor --contract FILE [--operation OP] [--env NAME] [--provider P] [--state-backend SPEC] [--live] [--json] [--strict]
fluid doctor --compare LEFT RIGHT
Examples
Run the built-in checks. With no flags, fluid doctor reports copilot readiness, the active memory-store backend and feature availability:
fluid doctor
Check one area, for example the binaries that deploy and sign:
fluid doctor --scope infra
fluid doctor — scope=infra
✓ binary:docker: 'docker' on PATH
✓ binary:helm: 'helm' on PATH
✓ binary:kubectl: 'kubectl' on PATH
✓ binary:tofu: 'tofu' on PATH
! binary:cosign: 'cosign' not found on PATH
fix: install 'cosign' (see https://agenticstiger.github.io/forge_docs/cli/doctor.html)
5 checks errors=0 warnings=1
That last fix: line points at this page. See Installing what doctor checks.
Gate a CI job on every check being clean:
fluid doctor --scope all --json | jq -e .ok
List the runtime switches the CLI recognises and what they are set to:
fluid doctor --env
Options
| Option | Description |
|---|---|
--scope {authoring|pipeline|ingestion|infra|catalog|all} | Run one group of checks, or all of them. There is no default scope: without --scope, fluid doctor runs the checks described under Without --scope. |
--env | List the recognised FLUID_* runtime switches with their current value, source and default behaviour. See --env. Alone, it keeps this meaning. (since 0.33.0, forge-cli #992) With --contract it takes a name, the environment overlay, as on plan and apply. |
--contract FILE | (since 0.33.0, forge-cli #992) Preflight a contract (or a .tgz bundle): can the operation run here? Offline. See --contract. |
--operation {validate,generate,plan,apply,ship} | (since 0.33.0, forge-cli #992) With --contract: the operation to preflight. Default plan, the offline plan. |
--live | (since 0.33.0, forge-cli #992) With --contract: add read-only checks of the identity and the state backend, for apply and ship. |
--provider P | (since 0.33.0, forge-cli #992) With --contract: the cloud apply provisions, as apply takes it. A contract on several clouds needs one for apply and ship. |
--state-backend SPEC | (since 0.33.0, forge-cli #992) With --contract: the OpenTofu state apply uses (s3://... or gcs://...), as apply takes it. Else FLUID_STATE_BACKEND. |
--compare LEFT RIGHT | (since 0.33.0, forge-cli #992) Compare two saved --contract --json reports and name the version gaps. |
--json | Machine-readable output. What it contains depends on the other flags; see --json. |
--features-only | Run only the feature-availability check and skip the rest of the default run. |
--strict | (since 0.27.0, forge-cli #786) Exit 1 whenever the summary says "Action needed", copilot readiness included. See --strict. (since 0.33.0, forge-cli #992) With --contract, it also exits 1 when a capability is lossy. |
--extended, --comprehensive | Also run a scripts/diagnose.sh that you provide in the current directory. See --extended. |
--out-dir DIR | Where --extended writes its diagnostic files. Default runtime/diag. |
--verbose, -v | Show detailed output. |
Without --scope
fluid doctor with neither --scope nor --env runs the default checks:
- Forge copilot readiness: whether an LLM provider and model are configured, and whether credentials are present. (since 0.29.0, forge-cli #850) Its Endpoint row says
Provider defaultwhen no endpoint is set and the provider picks its own address; through 0.28.0 it showed alitellm://<provider>/<model>label. A ready coding agent's row sayscoding-agent://<name>. WithFLUID_LLM_PROVIDERset toclaude-code,codex,cursororkiro, the copilot is ready when the agent's CLI (claude,codex,cursor-agentorkiro-cli) is onPATH; the CLI's own sign-in is not checked. Without the CLI, the table says Setup needed and the panel names it:The 'cursor-agent' CLI for cursor is not on PATH.Through 0.28.0 these providers read "No API key found". With nothing configured and no terminal, readiness reports the provider a non-interactive forge run picks, orNot selectedwhen that pick finds nothing; see When nothing is configured. (since 0.29.0, forge-cli #852) With no provider selected, the Message row that--verboseshows gives the same reason as forge'scopilot_no_llm_provider, for exampleNo LLM provider is selected: OPENAI_API_KEY, ANTHROPIC_API_KEY are all set, so none of them is chosen. Pick one with --llm-provider or FLUID_LLM_PROVIDER.Through 0.28.0 the row always readNo LLM provider configured. Run 'fluid ai setup' or set an API key env var., and forge fell back togeminiwhere readiness saidNot selected. Auser:password@in the endpoint shows as***:***@. (since 0.29.0, forge-cli #854) Readiness now walks the ladder a run walks, so the Provider row names what a run uses:FLUID_FORGE_AGENTcounts as naming the provider, and a provider thatFLUID_LLM_PROVIDERnames reports its catalog model, not the onefluid ai setupsaved; see Which provider a run uses. (since 0.29.0, forge-cli #853) The Auth row countsFLUID_LLM_API_KEYonly whenFLUID_LLM_PROVIDERorFLUID_FORGE_AGENTnames the provider. - Memory store backend: (since 0.31.0, forge-cli #881) The
postgresandvectorbackends are removed:FLUID_STORE_BACKEND=postgresorvectorlogs a warning and uses the file store, and the check reports the file store. In 0.29.0: which backend holds copilot memory (file,sqlite,postgresorvector), where it lives, and whether it is readable and writable. - Provider readiness: under
--verbose, a Databricks Provider row reportsNot configuredwhen noDATABRICKS_*workspace variable is set, and otherwise whether the credential resolves under the same rulesfluid applyuses, whetherDATABRICKS_WAREHOUSE_IDis set and whetherdatabricks-sdkis installed. It never opens a connection and never changes the exit code. See Databricks. - Feature availability: a table of CLI components (the schema manager, the sovereignty and agent-policy validators, the provider action parsers for GCP, AWS and Snowflake, the dbt engine, the copilot, the LiteLLM backend and the agent web tools), each marked available, not available or not installed.
--features-onlyprints just this table. (since 0.31.0, forge-cli #881) The agent web tools are removed, so the table no longer lists them.
It prints a summary panel followed by the readiness and backend tables; the feature table appears under --verbose or when a feature is missing. The exit code is 1 when a feature the CLI treats as critical is unavailable, and 0 otherwise. A missing LLM key, a missing Snowflake driver and a missing dbt install do not change it, except that --strict also fails a copilot that is not ready.
--strict
(since 0.27.0, forge-cli #786)
The summary panel says Action needed when a feature check fails or the copilot is not ready (its readiness table says "Setup needed"). Through 0.26.0 only the first case changed the exit code. A copilot that was not ready printed "Action needed" and the run still exited 0, so a CI gate on fluid doctor could never fail for it.
With --strict, fluid doctor exits 1 whenever the summary says "Action needed", in the text report and with --json. The default exit code does not change.
fluid doctor --strict
--json carries the reason. Next to store_backend the payload now has copilot_ready and action_needed, so a CI job can tell a failed feature check from a copilot that is not set up:
fluid doctor --json | jq '{copilot_ready, action_needed}'
{
"copilot_ready": false,
"action_needed": true
}
--strict belongs to the default run. --features-only prints no summary, and --scope and --env run their own checks, so all three ignore it.
--scope: what each scope checks
Each scope is a fixed list of checks. A check reports ok, warn or error.
| Scope | Checks | Severity when it fails |
|---|---|---|
authoring | schema:latest_version: the newest stable schema bundled with the CLI is at least 0.7.3. | error |
pipeline | dispatcher:acquisition_engines: the acquisition-engine dispatcher registers the expected six engines. Then one importability check for each runner module: duckdb, dlt, meltano, airbyte, kafka_connect and debezium. | error for the dispatcher, warn for a runner module |
ingestion | Python libraries importable: duckdb, dlt, httpx, snowflake.connector. | warn |
infra | Binaries on PATH: docker, helm, kubectl, tofu, cosign. | warn |
catalog | The datahub, openmetadata and datamesh_manager registrar modules import. | warn |
all | The checks of the five scopes above, in that order. |
Two things the scopes do not do. They do not check credentials, network reachability or LLM readiness; for credentials use fluid auth status. And a check that only looks at PATH or at import cannot tell you the tool works, only that it is present.
Exit codes and severity
Missing tools and libraries are warnings, not errors. fluid doctor --scope ingestion on a machine without duckdb prints three ! lines and exits 0. The exit code is 1 only when a check reports an error, which in the scopes above means a broken engine dispatcher or a bundled schema older than 0.7.3.
To fail a job on a missing tool, read the structured output instead of the exit code:
fluid doctor --scope infra --json | jq -e .ok
ok is true only when every check is ok, so a single warning makes it false and jq -e exits 1.
--json output
The shape depends on which surface you asked for:
| Invocation | JSON |
|---|---|
fluid doctor --scope <s> --json | {"scope", "ok", "results": [...]}, one result per check. |
fluid doctor --env --json | {"env": [...], "telemetry": {...}}. (since 0.31.0, forge-cli #888) {"env": [...]}, with no telemetry key. |
fluid doctor --json (no --scope, no --env) | The memory-store section, {"store_backend": {...}}. (since 0.27.0, forge-cli #786) It also carries copilot_ready and action_needed; see --strict. (since 0.31.0, forge-cli #893) It also carries secrets; see Secrets. Per-check results need --scope. |
A scoped result looks like this:
fluid doctor --scope authoring --json
{
"scope": "authoring",
"ok": true,
"results": [
{
"name": "schema:latest_version",
"severity": "ok",
"detail": "bundled latest version is 0.7.5",
"fix": null,
"doc": "https://agenticstiger.github.io/forge_docs/cli/doctor.html"
}
]
}
fix carries the remedy for a failed check and is null for a passing one. doc points at this page.
--env: the runtime switches
fluid doctor --env prints a table of the FLUID_* variables (and a few others, such as DBT_EXECUTABLE and DO_NOT_TRACK) that change how the CLI behaves. Each row shows the variable, its current value, a Source (env when you set it, default when you did not), the default behaviour and a one-line description. The last line of the output states whether anonymous telemetry is on; it is off unless you opt in. (since 0.31.0, forge-cli #888) DO_NOT_TRACK and FLUID_TELEMETRY are no longer listed, and the telemetry line is gone.
With --json, each row is an object:
fluid doctor --env --json | jq '.env[] | select(.name == "FLUID_FEDERATION_TIMEOUT_SECONDS")'
{
"name": "FLUID_FEDERATION_TIMEOUT_SECONDS",
"value": "(unset)",
"source": "default",
"default": "30s default",
"description": "Per-git-operation cap when `fluid apply` fetches a federated upstream digest; raise it for a genuinely large upstream repo"
}
This lists the switches fluid doctor knows about. (since 0.33.0, forge-cli #975) It lists the four settings of a Spark build with runtime: local (FLUID_SPARK_SUBMIT_EXECUTABLE, FLUID_SPARK_SUBMIT_PROPERTIES_FILE, FLUID_SPARK_LOCAL_ROOT and FLUID_SPARK_LOCAL_NAMESPACE_ALLOWLIST): see Operator settings for a local run. It is a convenient first look, not a substitute for the full table in Environment variables.
--contract: can this operation run here?
(since 0.33.0, forge-cli #992)
fluid doctor --contract answers one question before CI starts: can this operation run on this machine, for this contract? It reads the contract (or a bundle), resolves what the operation needs, and checks the machine against it. It is offline unless you pass --live: it fetches no schema, provider or tool, and installs nothing.
fluid doctor --contract contract.fluid.yaml --operation apply --env prod
The report names the schema revision the contract resolves to (with the sha256 of the bundled file), the Forge build, each extra against the pins this build declares, the plugins installed through entry points, tofu, dbt and spark-submit, the dbt adapters and the OpenTofu provider pins. Each capability the operation relies on is in one of four classes:
| Class | Meaning |
|---|---|
exact | The operation does what the contract declares |
lossy | It runs, and writes something other than what the contract declares, such as a geometry column written as GEOGRAPHY |
unsupported | It would be refused, such as a bare array column on BigQuery, or an extra that is not installed |
requires-live-proof | An offline check cannot tell, such as the cloud identity or the provider download |
fluid doctor --contract: validate (offline)
forge 0.32.0 · python 3.12.13 · darwin-arm64
schema 0.7.7 (bundled, preview)
needs: no cloud, credential or external tool
✗ unsupported (1)
[column-type] bigquery exposes[orders].tags: declared 'array', which BigQuery
holds only with its element or field types, and none is declared (fields,
element, or key and value need contract 0.7.7 or later)
fix: Declare the type's fields, element, or key and value (contract 0.7.7
or later), or declare json or string.
! lossy (1)
[column-type] bigquery exposes[orders].area: declared 'geometry', which is
planar, and BigQuery has only the spherical GEOGRAPHY; written as 'GEOGRAPHY'
fix: Declare geography if the coordinates are on the sphere.
not-ready: exact 1 · lossy 1 · unsupported 1 · requires live proof 0
The report lists the lossy and unsupported findings, and counts the exact ones: here, the third column of the contract is exact. Column types come from the type tables of the emitters, and every other finding from the rules and installed validators that fluid validate runs, so a column that fluid generate iac refuses is unsupported here first.
The operation. --operation is validate, generate, plan (the default, the offline plan), apply or ship. validate, generate and the offline plan need no cloud, credential or tool, so a catalog-only contract on AWS lists no AWS identity. apply and ship also list the extras for the cloud, tofu, dbt and its adapter or spark-submit where the contract builds with them, the provider pins, the cloud's identity and the state backend. The identity, the provider pins and a remote state backend (s3:// or gcs://) are requires-live-proof. The default local state is lossy, because apply then keeps its OpenTofu state on this machine, where another runner cannot see it, so --strict exits 1. A state spec that cannot be read is unsupported. They resolve the cloud and the state backend as apply does, so a contract on several clouds needs --provider, and --state-backend (else FLUID_STATE_BACKEND) names the state. --env NAME applies an environment overlay, as plan and apply do.
Verdict and exit codes. The summary line ends in a verdict. not-ready means a capability is unsupported, and exits 1. ready exits 0, with its lossy findings listed. needs-live-proof means nothing is unsupported and something still needs --live to prove, and exits 0. --strict also exits 1 on lossy.
--live. For apply and ship, --live adds read-only checks, one attempt each: the identity (AWS GetCallerIdentity, a GCP token refresh) and whether the state bucket is reachable. It prints no identity. A check that passes makes its capability exact, and one that fails makes it unsupported, so the run exits 1. For validate, generate and plan it says that no live check applies. Without --live the preflight makes no network call. A failed check names the cloud's status code and never its message, because the message can name the identity or the bucket. A check it cannot run, because the SDK is not installed, is listed as skipped, for example live gcp-identity: skipped (google is not installed).
--json. --json writes the report as one document in the format fluid-preflight/1, with the keys version, operation, mode, forge, schema_revision, contract, env, needs, extras, plugins, tools, adapters, state_backend, capabilities, validation and summary, and live_checks with --live. Each capability has an area, a class, a subject, a target, a detail and a fix. A report holds no environment value, so no path, account, bucket or variable value, and it goes through both redaction layers.
--compare. Run the preflight in two places, save each --json report, and compare them:
fluid doctor --contract contract.fluid.yaml --json > laptop.json
fluid doctor --contract contract.fluid.yaml --json > ci.json
fluid doctor --compare laptop.json ci.json
2 difference(s) (left vs right):
[forge] version: 0.32.0 vs 0.31.0
Pin one Forge version.
[tool] tofu: 1.13.1 vs 1.11.0
Install the same tofu version on both (this build needs >=1.12).
It exits 1 when the reports differ in anything it compares: a version, the operation, the environment, the contract or a capability class. With --json it writes the differences as a document in the format fluid-preflight-compare/1.
Errors:
| Event | Exit | Raised when |
|---|---|---|
doctor_preflight_failed | 2 | --operation, --live, --provider, --state-backend or --env NAME is given without --contract (--live needs --contract), --contract or --compare is given with --scope, --extended, --features-only or each other (--contract runs on its own; drop --scope), --env has no overlay name with --contract, or a --compare file is not a fluid-preflight/1 report |
doctor_preflight_failed | 1 | The contract is malformed or cannot be read (cannot load the contract) |
contract_file_not_found | 1 | The --contract file does not exist |
file_not_found | 1 | A --compare report does not exist |
Run it offline, as a gate, before a pipeline starts, and run it with --live on the runner that will apply to learn whether it can reach the cloud and the state.
--extended
fluid doctor --extended runs bash scripts/diagnose.sh, resolved relative to the current directory, with FLUID_DIAG_OUT_DIR set to --out-dir. As of 0.18.1 the data-product-forge package and the forge-cli repository do not include that script, so --extended works only in a directory where you have put one. Anywhere else the command prints the default report and then fails:
CLI command error
❌ Extended diagnostics are not installed in this checkout. [ERR_DOCTOR_EXTENDED_UNAVAILABLE]
script: /path/to/project/scripts/diagnose.sh
readme: /path/to/project/scripts/README.md
hint: Run `fluid doctor` for built-in checks only.
The exit code is 1. Leave --extended out unless your project provides its own scripts/diagnose.sh.
The 0.28.0 install change
(from 0.27.0) fluid doctor prints one line once per run. On 0.27.0 it reads:
AI/MCP move to extras in 0.28.0: pip install 'data-product-forge[standard]'
(since 0.28.0, forge-cli #837) On 0.28.0 the notice reads AI and MCP are extras since 0.28.0: pip install 'data-product-forge[standard]' and prints only when litellm or mcp is not installed (0.27.0 printed it every run), and a configured provider is no longer reported as ready when litellm is missing: the Next steps panel says <provider> needs litellm, which is not installed and prints pip install 'data-product-forge[litellm]'.
It also reports three optional packages in the AI checks: the LiteLLM backend, the MCP SDK and the OpenLineage client. Each shows its version when installed, or Not installed (optional) with the pip install 'data-product-forge[<extra>]' line. None of them is imported: doctor reads the version from the package metadata, so it makes no network call for litellm's cost map.
Installing what doctor checks
The fix: line for a missing binary, and the doc field in --json output, point at this page. A warning matters only when you use the command that needs the tool.
| Check | Needed by | Install |
|---|---|---|
tofu | fluid apply against aws, gcp, snowflake and confluent bindings, which compile the contract to OpenTofu and run tofu. | Run fluid apply --ensure-opentofu: if tofu is missing, the CLI downloads a pinned, SHA-256-verified build before the apply. Or install it from opentofu.org. Pin a version with FLUID_OPENTOFU_VERSION. |
cosign | fluid bundle --sign and fluid verify-signature. | brew install cosign, or see the cosign installation guide. |
docker | Managed-mode acquisition engines that provision infrastructure with Docker Compose. See Source-aligned acquisition. | Docker's install guide. |
helm, kubectl | Managed-mode acquisition engines that provision infrastructure with Helm on Kubernetes. | Helm install guide and Kubernetes tools. |
duckdb | The local provider and DuckDB acquisition builds. | pip install "data-product-forge[local]", which installs duckdb at the version the CLI requires for its contract-SQL sandbox. See DuckDB sandbox. |
dlt | dlt acquisition builds. | pip install dlt. As of 0.18.1 data-product-forge has no dlt extra. |
litellm, mcp, openlineage | (from 0.27.0) AI forge, fluid mcp serve and lineage emission. | Part of a base install through 0.27.0; since 0.28.0 install them with pip install "data-product-forge[standard]", or [ai], [mcp] or [lineage] for one. (since 0.28.0, forge-cli #837) |
httpx | A core dependency of the CLI. | Installed with data-product-forge; a failure here points to a broken Python environment. |
snowflake.connector | The snowflake provider. | pip install "data-product-forge[snowflake]". The fix: line for this check reads pip install snowflake, which is not the package that provides the connector; use the extra. |
The pipeline and catalog scopes check modules that ship inside data-product-forge. If one fails to import, reinstall the package rather than installing a separate library:
pip install --force-reinstall data-product-forge
Secrets
(since 0.31.0, forge-cli #893) fluid doctor prints a Secrets table. It shows the schemes that may resolve, the stages that may fetch a value, the locator prefixes, the number of destination allowlist entries and, when they are set, the run-secrets file with its reference count, the credential store, and the Vault or OpenBao address with its auth method and status. A last row says whether boto3 is installed for aws-sm://.
fluid doctor --json carries the same facts under secrets: schemes_enabled, prefixes, stages_that_resolve, stages_that_never_resolve, destination_entries, run_secrets_file, credential_store, vault (address, auth method, reachability, token TTL), aws_sm and packs. The report never prints a value, never unwraps a wrapped token and never makes a JWT login. fluid secrets explains each setting.
Notes
- (since 0.31.0, forge-cli #905) With
SNOWFLAKE_AUTHENTICATOR=WORKLOAD_IDENTITY, the Snowflake check does not ask forSNOWFLAKE_USER. See Workload identity federation. - Use
fluid describe --selfto read what the CLI ships.describereports what is installed;doctorreports whether the tools around it are present. - For the first response to a failed run, the sequence in Production troubleshooting starts with
fluid doctor.