DoctorCopy Anchor Link

farm doctor brings Farm's runtime diagnostics to the terminal and CI. It reads the same runtime snapshot that powers DevTools, so a live application reports its resolved routes, APIs, middleware, integrations, storage, schedules, and deployment settings. When no app is running, Doctor falls back to inspecting the project itself.

Run DoctorCopy Anchor Link

Run this from the application root:

farm doctor

The command probes http://localhost:3000/__farm/devtools.json. When the app is running, the live snapshot is the source of truth:

FARM / DOCTOR
storefront / LIVE RUNTIME

PASS  Connected to the Farm runtime
      8 pages, 4 API routes, and 2 middleware layers are registered.
WARN  Production storage is in memory
      vercel instances do not preserve in-memory data across executions.

SUMMARY  2 passed / 1 warning / 0 failed / 1 info
DEVTOOLS http://localhost:3000/__farm/devtools

When the dev server is not running, or when DevTools is disabled, Doctor automatically falls back to project inspection. It loads farm.config.*, validates the package manager and workspace links, checks generated types and renderer entrypoints, checks the app router and root layout, resolves the deployment target, and inspects integrations, KV storage, and cron configuration.

Target another serverCopy Anchor Link

Use a port:

farm doctor --port 4319

Or pass the complete origin:

farm doctor --url http://localhost:4319

When an explicitly requested server cannot be reached, Doctor reports LIVE_RUNTIME_UNREACHABLE and continues with project checks. This keeps the command useful while making the failed probe visible.

Offline checksCopy Anchor Link

Skip the live probe when the command must use only repository state:

farm doctor --offline

Offline mode checks:

• Node.js satisfies Farm's supported baseline.
• package.json exists and declares @farm.js/core.
• The selected package manager is unambiguous, and pnpm satisfies Farm's supported baseline.
• workspace:, file:, link:, and portal: dependencies resolve locally.
• Farm config loads and resolves for development.
• Generated route, API, environment, content, and i18n declarations are current.
• The selected renderer's Vite, server, and client entrypoints resolve.
• Configured integration entrypoints load, and declared Farm packages are installed.
• Feature packages that Farm loads from the app are installed when the app uses the feature: @tailwindcss/vite for a stylesheet that imports tailwindcss (a warning), @vercel/og for a generated opengraph-image/twitter-image or an @farm.js/core/og import (a failure), and sharp for an @farm.js/core/image import (a warning) or images.provider: "node" (a failure), and @farming-labs/docs when docs are enabled (a failure).
• The app directory or programmatic router contains page routes.
• A root layout is available from the app or an extended layer.
• Deployment target, preset, and output directory resolve.
• Integrations and KV mounts are visible in config.
• Configured cron routes have matching app-directory API route files.
• Serverless targets do not depend on explicitly configured in-memory root KV storage.

Live mode is more complete because it sees generated and programmatic API routes, inherited runtime settings, loaded middleware, and discovered workflows after Farm initializes the app.

Doctor is read-only by default. It does not install packages, run package-manager scripts, contact integration providers, or update generated artifacts. Config loading follows the same behavior as other Farm CLI commands, so only run it in a project whose configuration you trust. The separate --fix option remains an explicit opt-in for the safe additive corrections described below.

Check the beta release channelCopy Anchor Link

Registry checks are opt-in because ordinary Doctor runs do not contact npm:

farm doctor --offline --registry

This verifies that @farm.js/core@beta and @farm.js/create-app@beta point to published versions. When the project declares an exact Farm version, Doctor also warns when that version is behind the current beta tag. A registry outage produces a warning instead of hiding the local project results.

JSON and CICopy Anchor Link

Print a structured report:

farm doctor --offline --json

A report includes source, health, project and target metadata, status totals, and the individual checks. Live reports also include runtime counts and a DevTools URL.

Doctor uses these health rules:

This makes a basic CI check straightforward:

farm doctor --offline
farm build

Use farm doctor --offline --json when CI should store or process the report. Keep farm build as the final production compatibility check because it validates bundling and adapter output, not only project structure.

DiagnosticsCopy Anchor Link

Common diagnostic codes include:

Warnings identify behavior that can be valid locally but needs attention before production. Failures mean the project cannot satisfy a basic framework contract.

SecurityCopy Anchor Link

Doctor reads the development snapshot described in Runtime JSON. A report contains project paths, route structure, integration names, package versions, and environment key names, but never environment values, provider credentials, storage connection details, request data, cookies, or application records. farm doctor --json follows the same rule. --registry contacts only the public npm registry; provider services are never probed.