Validation diagnostics

Every problem code opend validate, the previewer, the web editor and the hosted build report, what it means and how to fix it.

Reading a diagnostic

topics/install.dita:14:9: error [broken-link] link target not found: setup.dita

That is the file, line and column, the severity, the code and a message. An error fails validation and stops a hosted build from publishing. A warning does not, unless you validate with --strict. Codes are stable, so tools can filter on them.

Project files

Code	Severity	Meaning	Fix
`missing-config`	error	`opend.config.yaml` is not in the folder you validated.	Pass the docs root, or create the file.
`invalid-config`	error	The config is not valid YAML, or a field breaks its rules. The hosted build also reports it when `release` is not a version number.	Follow the message, which names the field. See opend.config.yaml reference.
`missing-ditaval`	error	The `buildFilter` file does not exist.	Fix the path, which is relative to the docs root.
`invalid-ditaval`	error	The DITAVAL root is not `<val>`, or a `prop` has an unknown `action`.	Use `include`, `exclude`, `flag` or `passthrough`.
`missing-theme`	error	The `theme` file does not exist.	Fix the path.
`missing-logo`	error	The `logo` file does not exist.	Fix the path.
`duplicate-publication`	error	Two publications have the same file name, so only one could be downloaded at `/pdf/<name>.pdf`.	Rename one bookmap.
`invalid-preview-contexts`	error	`preview-contexts.yaml` is not valid YAML, or a reader is malformed, for example without a `version`. Reported by the CLI only.	See preview-contexts.yaml reference.
`xml-syntax`	error	A topic, map or DITAVAL file is not well-formed XML.	Look at the line and column: an unclosed tag, a stray `&` or `<` (write `&` and `<`, or use CDATA), or an unknown entity.

Maps and topics

Code	Severity	Meaning	Fix
`missing-map`	error	The root map, or a map a `mapref` points at, does not exist, or a `mapref` has no usable `href`.	Fix the path.
`map-cycle`	error	Maps reference each other in a loop. The message shows the chain.	Remove one `mapref`.
`missing-topic`	error	A `topicref` points at a file that does not exist, or that is not a `.dita` or `.xml` file.	Fix the `href`.
`unsupported-topicref`	warning	A `topicref` points at an external URL, or has a `format` other than `dita`. It is skipped.	Link to external pages from a topic with `xref` instead.
`empty-topicref`	warning	A navigation entry has neither an `href` nor a `navtitle`, so it has nothing to show.	Add one, or use `topicgroup` to group without a heading.
`not-a-topic`	error	A file a map references has no topic root element.	Make the root a topic type, or point the map elsewhere.
`missing-id`	error	A topic's root element has no `id`.	Add one; references use it.
`duplicate-id`	error	Two elements in one topic share an `id`.	Rename one, and update references to it.
`unsupported-element`	warning	An element is outside the supported subset. It renders as a plain block.	Use a supported element: see Supported DITA subset.
`conflict-markers`	error	The web editor refused a save, or a conflict resolution, because the text still has conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`), such as those in the hand-edit box when you resolve a conflict.	Keep the text you want from each side and delete the marker lines, then save again.
`unreferenced-topic`	warning	A topic file is in no map, and no published topic reuses content from it. It is usually forgotten.	Add it to a map, reuse a chunk from it, or delete it.

Conditions

Code	Severity	Meaning	Fix
`undeclared-value`	error	A filtering attribute has a value that is not declared in `opend.config.yaml`, or the attribute has no declared values at all. Readers never see that content.	Fix the typo, or declare the value under `attributes`.
`invalid-release`	error	A `release` token is not a version or range. Readers never see that content.	Use `1.4`, `2.0..`, `..1.9` or `1.2..1.9`. See Release range grammar.

Links, images, keys and reuse

Code	Severity	Meaning	Fix
`broken-link`	error	A link points outside the docs root, or at a file, topic or element that does not exist.	Fix the `href`. Same-file links take `#topic-id/element-id`.
`link-to-unpublished`	warning	A link points at a topic that is not in the site navigation, so every reader sees plain text.	Add the target to the site map (with `toc="no"` to keep it unlisted), or remove the link.
`missing-image`	error	An image file, or the file a key for an image names, does not exist.	Fix the path, relative to the topic or map.
`unresolved-key`	warning for `keyref`, error for `conkeyref`	The key is not defined in the keyspace of the map publishing this topic. A `keyref` falls back to the element's own content; a `conkeyref` pulls nothing.	Define the key, or pull the shared key map into this map or bookmap with a `mapref`.
`missing-conref`	error	A `conref` is not of the form `file#topic/element`, its file, topic or element does not exist, or a `conkeyref` key has no local `href`.	Check the ids in the chunks file.
`conref-cycle`	error	Content references pull each other in a loop. The message shows the chain.	Break the loop.
`conref-type-mismatch`	warning	An element pulls a chunk of a different element type, such as a `p` pulling a `note`. The chunk is used as it is.	Make the referencing element the same type as the chunk.
`unsupported-conref`	warning	The element uses `conrefend` or `conaction`. Only the start element is pulled.	Reference each element separately, or wrap the range in one element with an id.

Context-sensitive help

Code	Severity	Meaning	Fix
`invalid-resourceid`	error	A `resourceid` lacks `appname` (the host app) or `appid` (the context key).	Give both.
`duplicate-context`	error	Two topics claim the same app and key without conditions, so the second could never be shown.	Add conditions to tell them apart, or use a different key.
`invalid-help-contexts`	error	`help-contexts.yaml` is not valid YAML, does not match the expected shape, or has a bad route pattern.	See the help-contexts.yaml reference.
`unknown-context`	error	A route or default in `help-contexts.yaml` maps to a key that no topic declares, nor any parent of it.	Add a `resourceid` for the key, or fix the key.

Where diagnostics appear

In the terminal, from opend validate and opend preview.
In the previewer's banner, and at /_opend/diagnostics.json.
As GitHub workflow annotations with --format github.
On the hosted platform: a failing push shows a failed opend/build commit status with the first errors, and the full list is in the build's record from the admin API.