Fix a failing check

Your PR’s docmeta check is red and you’d like it green again. You’re in the right place. This page decodes the error, points you at the exact field and line to change, and shows you how to confirm the fix locally before you re-push. You don’t need to know how docmeta was set up, only what its output is telling you.

The fastest path

Find your error message in the common failures below, apply the matching fix, then run docmeta locally to confirm it’s green. Done.

Decode the error line

A failing file in pretty output (the default) looks like this:

✗ docs/guide.md
    (root)  must have required property 'type'  [google:okf:0.1]

The first line is the file that failed. Each indented line below it is one problem, in this shape:

<field>  <message>  (line N)  [schema-id]

Part	What it tells you
<field>	Which field is wrong. It’s a JSON Pointer such as /timestamp, or a bare key name. (root) means the document as a whole — most often a required field is missing entirely.
<message>	What’s wrong, e.g. must have required property 'type' or must match format "date-time".
(line N)	The source line of the offending field, when docmeta can locate it. A missing required field has no line, so this part is absent.
[schema-id]	The schema that flagged it, e.g. google:okf:0.1. Useful when more than one schema applies.

Note

Need machine-readable output instead? --format json gives you the same information as structured data, and --format github emits inline PR annotations. See the output reference for the exact shapes.

Common failures

These cover the overwhelming majority of red checks. The first four are problems in your document; the last, Schema not found, is a setup problem rather than something in your file. Each shows the error, the cause, and a fix.

Missing a required field

✗ docs/guide.md
    (root)  must have required property 'type'  [google:okf:0.1]

The schema requires a field your frontmatter doesn’t have. The field name is in the message: here, type. The location is (root) because the field is absent, so there’s no line to point at.

Fix: add the field to your frontmatter.

docs/guide.md

---
title: My Guide
description: A short summary of this guide.
type: concept
---

Tip

Not sure what value type should be? The built-in OKF schema accepts any non-empty string. Pick the kind of doc this is, such as concept, guide, or reference. If your repo uses a custom schema, it may restrict type to a specific list; the error message will say so (for example, must be equal to one of the allowed values).

A value in the wrong format

✗ docs/guide.md
    /timestamp  must match format "date-time"  (line 4)  [google:okf:0.1]

The field is present, but its value doesn’t match the format the schema expects. Here timestamp must be an ISO 8601 date-time, and the file has something like last Tuesday:

docs/guide.md

---
type: concept
title: My Guide
timestamp: last Tuesday
---

The /timestamp pointer and (line 4) take you straight to the offending line.

Fix: replace the value with a properly formatted one. An ISO 8601 date-time looks like 2026-06-25T10:00:00Z:

docs/guide.md

---
type: concept
title: My Guide
timestamp: last Tuesday
timestamp: 2026-06-25T10:00:00Z
---

The same pattern applies to other formats: a uri field needs a full URL (https://example.com/...), and an enum field needs one of its allowed values. The message names the format or constraint that failed.

No frontmatter at all

✗ docs/guide.md
    (root)  must have required property 'type'  [google:okf:0.1]

A file with no frontmatter block reads as empty metadata, so it fails the same way a file missing a required field does. If you expected this file to have metadata, it’s probably missing its opening --- fence, or the block isn’t at the very top of the file.

Fix: add a frontmatter block at the top of the file, between --- fences (or +++/;;; for TOML/JSON):

docs/guide.md

---
type: concept
title: My Guide
---

# My Guide

Body content goes here.

Caution

The frontmatter block must be the first thing in the file. A blank line or any text above the opening --- means docmeta won’t recognize it as frontmatter.

A frontmatter parse error

✗ docs/guide.md
    (root)  Invalid YAML frontmatter: <parser detail>  [(parse)]

The frontmatter block exists but isn’t valid, so docmeta can’t read it. The message names the flavor (Invalid YAML frontmatter, Invalid TOML frontmatter, or Invalid JSON frontmatter), and the schema in brackets is [(parse)] rather than a real schema id, so this is a syntax problem, not a rule violation.

Fix: correct the block’s syntax for its flavor. In YAML a frequent culprit is a value with a colon that needs quoting:

docs/guide.md

---
type: concept
title: Versioning: a primer
title: "Versioning: a primer"
---

In JSON, the usual culprits are a trailing comma or an unquoted key; in TOML, an unquoted string or a malformed [table] header. See frontmatter flavors for each flavor’s fences and syntax.

Tip

The parser detail after the colon (truncated as <parser detail> above) usually points at the line and character where parsing broke. Read it closely It’s the fastest clue.

Schema not found

Sometimes docmeta stops before validating any file and prints a single line to stderr, prefixed with docmeta::

docmeta: Unknown built-in schema "google:okf:0.2". Available: google:okf:0.1.

or:

docmeta: Schema file not found: "./schemas/my.schema.json".

This isn’t a problem with your document. It’s a configuration problem. docmeta couldn’t load the schema it was told to use, so it can’t validate anything. This exits with code 2 (an operational error), not 1.

Fix: this usually isn’t yours to fix in a content PR. Check that the schema reference (in docmeta.config.yaml, a $schema field in your file, or a --schema flag) points at a schema that exists. A misspelled built-in id, a wrong file path, or an unreachable URL all produce this. If you didn’t change the schema setup, flag it to whoever maintains the repo’s docmeta config.

Reproduce and confirm locally

Don’t guess and re-push. Run the exact check on your machine so you see green before CI does.

1. Run docmeta on just your file. No install needed:

   npx docmeta validate docs/guide.md

   You’ll see the same ✗ and error lines CI showed you.

2. Apply the fix from the matching section above.

3. Run it again and confirm the green check:

   ✓ docs/guide.md
   
   1 file checked, 1 passed, 0 failed, 0 errors

4. Re-push. With a passing local run, your CI check should now be green too.

Tip

If your repo has a docmeta.config.yaml, running npx docmeta validate with no path validates the same fileset CI does, using the same schema. To match CI exactly, run it from the repo root.

Let docmeta draft the fix

When the failure is a missing field rather than a malformed one, and especially when several pages fail the same way, docmeta fill can propose the values for you. It reads the page, resolves the same schema the check used, and writes back the values it is confident about.

Preview first:

docmeta fill docs/intro.md --dry-run

✓ docs/intro.md
    /description  A tour of the CLI and its four commands.  0.91
    below 0.7: /resource 0.38

anthropic/claude-sonnet-4-5 · Threshold 0.7 · 1 file · 1 field would be written · 1 skipped

Then apply it and check your work with the command that flagged the problem:

docmeta fill docs/intro.md && docmeta validate docs/intro.md

Caution

fill edits the file in place. --dry-run is the preview. Review the diff before you commit; treat a proposed description as a first draft.

fill picks an LLM provider by detecting one, so it runs with whatever credentials you have — and, with none at all, falls back to a local model it downloads on first use. The report’s first line names what it used. On a machine with no API key, pass --provider or see the fill reference before the first run, so the download is a choice rather than a surprise.

Anything below the confidence threshold is skipped and named, so you still get a short list of what needs you. fill leaves any field that is already present and valid exactly as it is, and its confidence scores stay in the report.

fill won’t help with a malformed value it can’t improve on, or with a schema not found error. Those are the setup problems in the next section.

What the exit code means

docmeta’s exit code is the contract CI gates on. If you’re scripting the check or reading raw CI logs, here’s what each code means:

Code	Meaning
0	Every file passed. The check is green.
1	One or more files failed validation — a missing or malformed field. This is the red check you came here to fix.
2	An operational error — docmeta couldn’t run the check at all. A missing or unreadable schema, an unsupported file type, or no files to validate. The message goes to stderr, prefixed docmeta:.

A code 1 means fix your document. A code 2 means fix the setup. See Schema not found above, or escalate to whoever configured docmeta.

Still stuck?

If the error doesn’t match anything here, the Reference section documents every output format, exit code, and schema-resolution rule. To understand which schema applied to your file and why, see how schema resolution works.

Output formats & exit codesThe full pretty, JSON, and GitHub output shapes, and the 0/1/2 exit-code contract.