Doctor

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 Doctor

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 manifest, checks the app router and root layout, resolves the deployment target, and inspects KV storage and cron configuration.

Target another server

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 checks

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.
• Farm config loads and resolves for development.
• 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.

JSON and CI

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.

Diagnostics

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.

Security

Doctor reads the development snapshot described in Runtime JSON. A report contains project paths, route structure, integration names, 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.