--- title: "Doctor" description: "Run Farm's runtime diagnostics from the terminal and CI, against a live app or from project state alone." canonical_url: "https://mcp.farmjs.dev/docs/doctor" markdown_url: "https://mcp.farmjs.dev/docs/doctor.md" last_updated: "2026-10-20" x_farming_labs_generated_preamble: true --- # Doctor URL: /docs/doctor LLM index: /llms.txt Description: Run Farm's runtime diagnostics from the terminal and CI, against a live app or from project state alone. # Doctor `farm doctor` brings Farm's runtime diagnostics to the terminal and CI. It reads the same runtime snapshot that powers [DevTools](/docs/plugins/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: ```bash farm doctor ``` The command probes `http://localhost:3000/__farm/devtools.json`. When the app is running, the live snapshot is the source of truth: ```txt 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 server Use a port: ```bash farm doctor --port 4319 ``` Or pass the complete origin: ```bash 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: ```bash 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 channel Registry checks are opt-in because ordinary Doctor runs do not contact npm: ```bash 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 CI Print a structured report: ```bash 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: | Result | Exit behavior | | ----------- | ------------------------------------------ | | `ready` | No failed or warning checks; exits 0. | | `attention` | At least one warning; exits 0. | | `error` | At least one failed check; exits non-zero. | This makes a basic CI check straightforward: ```bash 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: | Code | Meaning | | ------------------------------ | ------------------------------------------------------------ | | `NO_PAGE_ROUTES` | Farm found no page modules or programmatic page router. | | `ROOT_LAYOUT_MISSING` | The app has no shared root layout. | | `CRON_ROUTE_MISSING` | A configured schedule targets an API route Farm cannot find. | | `CRON_SECRET_NOT_SET` | Scheduled production requests do not yet have `CRON_SECRET`. | | `EPHEMERAL_PRODUCTION_STORAGE` | A serverless deployment uses in-memory root KV storage. | | `ROUTE_RUNTIME_UNRESOLVED` | Farm could not resolve a page's inherited runtime controls. | | `LIVE_RUNTIME_UNREACHABLE` | An explicitly selected running app did not answer the probe. | | `PACKAGE_MANAGER_CONFLICT` | The package-manager field and workspace lockfiles disagree. | | `LOCAL_PACKAGES_MISSING` | A local or workspace dependency cannot be resolved. | | `GENERATED_ARTIFACTS_STALE` | Committed generated declarations need `farm generate`. | | `RENDERER_ENTRYPOINTS_MISSING` | A configured renderer export cannot be resolved. | | `OPTIONAL_PACKAGE_MISSING` | The app uses a feature whose package it has not installed. | | `REGISTRY_BETA_MISSING` | A required Farm package has no usable npm beta tag. | | `FARM_BETA_STALE` | An exact Farm dependency is behind the npm beta tag. | 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](/docs/devtools#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. ## Sitemap See the full [sitemap](/sitemap.md) for all pages. Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md). Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).