Troubleshooting

Read the whole output before fixing anything. check reports every problem in one run, each at file:line:col with the source line, a caret, one or more = hints and an MRD-nnnn code. Fix the first error in each file first: a file that fails to load can cause later errors that are only consequences (an unknown key in routes.yaml also produces “home type page has no route”). Then run the command again. Error codes has every code’s cause and fix.

How to read a diagnosticCopy Anchor Link

config/sites/main/routes.yaml:5:76: unknown field "pagniate"
    5 |   - { type: walk, id: rte_34agwcmxkh, uri: "/walks/{slug}", index: /walks, pagniate: 12 }
      |                                                                            ^
      = did you mean "paginate"?
      = error code MRD-1006

The path, line and column; the source line; the caret under the problem; hints (=), the first usually the fix; the code. A line with warning: does not fail check (except under --strict), but most warnings are real defects on a public site: fix them.

Quirks of the output to expect:

• Template warnings are not counted. check prints them (_shared/base.html:3:1: warning: ...) and then a summary such as 0 errors, 0 warnings; --strict does not fail on them and --json leaves them out. Read every line, not the summary.
• A template error is printed twice, once as _shared/page/entry.html:3:5: error: ... and once as templates/_shared/page/entry.html:3:5: ... with the source line. It is one problem.
• Problems in endpoints.yaml are reported at the endpoint’s line with column 0 (endpoints.yaml:2:0), not at the key that is wrong. Read the message for the key.
• Commands that start the engine (render, describe route, seed apply, mail) print log lines (level=INFO ... database connected) on standard error before their result. With --json the result is on standard output alone; a command that fails prints its error after the log lines.
• Hints sometimes cite design documents by file name (such as 27-frontend-toolkit.md). They are not in the handbook: search https://docs.cherwell.studio/llms-full.txt for the topic.

ConfigurationCopy Anchor Link

TemplatesCopy Anchor Link

The dev verbsCopy Anchor Link

Some verbs write a valid change that leaves follow-up work: dev endpoint add writes an endpoint whose templates you must then write, dev route add without --scaffold a route whose templates are missing, and dev route add --index with --scaffold still leaves index.html to engine-dmo new template <type>/index.html. Run engine-dmo check after every verb.

Schema plan and applyCopy Anchor Link

Seeding and contentCopy Anchor Link

RenderCopy Anchor Link

Accessibility auditCopy Anchor Link

engine-dmo a11y audit exits 1 on any failure. Each finding names its rule:

Server start (dev up and serve)Copy Anchor Link

Production checkCopy Anchor Link

ENVIRONMENT=production engine-dmo check --no-db reports in groups, so fix and run it again until it passes. Typical findings: server.security.signing_key is required in production (add security: { signing_key: ${SIGNING_KEY} } under server:), a real IP header is configured but server.trusted_proxies is empty (list the proxy’s addresses, or real_ip_header: "" with nothing in front), the log driver is development only (configure smtp, postmark, ses or resend with mail.from), and require_mfa: false refused. See Configuration and secrets.

ExtensionsCopy Anchor Link

check reports each loader problem at its line in engine.yaml. The common ones: this engine is a pure Go build, which cannot load extensions (run a cgo build such as the -vips image), and does not match this engine (...) followed by each difference (Go version, platform, -trimpath, meridian-extend version). The full list is in Extensions.

When you are stuckCopy Anchor Link

flowchart TD
  start["Something failed"] --> read["Read every line of<br/>engine-dmo check"]
  read --> see["Print what the engine sees:<br/>describe route, describe type,<br/>config render"]
  see --> search["Search the handbook for<br/>words from the message"]
  search --> fix["Smallest change<br/>that could fix it"]
  fix --> loop{"Loop passes?"}
  loop -- yes --> done["Carry on"]
  loop -- "no, and the engine<br/>cannot do it" --> tell["Tell the person;<br/>doctor --out doctor.txt"]
  loop -- "no, another idea" --> fix

1. Run engine-dmo check and read every line.
2. Print what the engine sees: describe route <path> --json, describe type <key>, config render.
3. Search the handbook for a few words of the message: https://docs.cherwell.studio/llms-full.txt.
4. Make the smallest change that could fix it and run the loop again.
5. If the engine cannot do what is needed, say so to the person with the message and what you tried. engine-dmo doctor --out doctor.txt writes a support bundle they can send on.