Diagnostics: the content model
The diagnostics about ascribe.toml’s file, project, sources, content types, and names, and how to fix each.
For AI agents: the documentation index is at llms.txt, and this page is available as Markdown.
The problems Ascribe reports in ascribe.toml. One that’s an error stops everything else: every other check depends on the content model. This page has the file through its names; [releases], phrases, widgets, the consumer, builds, the editor, [permalinks], [crawlers], [listing], and [checks] are on Diagnostics: the content model’s builds and site. Part of the diagnostics reference, which says what an entry’s severity, level, and next step mean, and has an index of every diagnostic.
The file
ASC060 model-toml-syntax
Error · file level · next step: write · SPEC §7.1
When: ascribe.toml isn’t valid TOML.
Message: ascribe.toml isn’t valid TOML: {detail}
Fix: Fix the TOML syntax at the place the message names.
Read more: The file in the ascribe.toml reference.
ASC061 model-unknown-key
Error · file level · next step: choose · SPEC §7.1
When: A table of ascribe.toml has a key this version of Ascribe doesn’t know.
Message: unknown key {key} in [{table}]; this is ascribe {version}, and the project may need a newer one
Fix: Fix the key’s spelling, or remove it. A key added in a later version of Ascribe is unknown to an older one: when the project was written for a newer Ascribe, install it. A content type has no files or default: each page names its type in its frontmatter, as type: how-to, so remove them and add type: to the type’s pages. The glossary has no terms: write each term as a heading marked @term on a glossary page, with its definition as the paragraph under it, and list the page in [glossary] pages. [[intended]] has no term: acknowledge a term’s problem with @intended under its heading. [consumer] has no headers: write host = "netlify", which writes Netlify’s _headers as headers did, and _redirects beside it. ascribe.toml has no [permalinks]: ascribe addresses init moves its retired permalinks and aliases into ascribe.addresses, as go:<name> keys of [retired] and [moved].
Read more: The file in the ascribe.toml reference.
ASC062 model-missing-key
Error · file level · next step: write · SPEC §7.1
When: A table of ascribe.toml is missing a key it requires.
Message: [{table}] is missing the required key {key}
Fix: Add the key.
Read more: The file in the ascribe.toml reference.
ASC063 model-wrong-type
Error · file level · next step: write · SPEC §7.1
When: A key’s value is of the wrong type, such as a number where a string is required.
Message: {key} must be {expected}, but it’s {found}
Fix: Give the key a value of the expected type. Strings are always quoted in TOML.
Read more: The file in the ascribe.toml reference.
ASC064 model-invalid-value
Error · file level · next step: choose · SPEC §7.1
When: A key’s value isn’t one of the values the key allows.
Message: {key} can’t be “{value}”; use one of: {values}
Fix: Use one of the values the message lists.
Read more: The file in the ascribe.toml reference.
ASC065 model-spec-unsupported
Error · file level · next step: choose · SPEC §11
When: spec names a specification version this version of Ascribe doesn’t implement.
Message: ascribe.toml targets spec version “{spec}”, but this processor implements {supported}
Fix: Set spec = "0.1", the specification version this release implements, or update Ascribe.
Read more: Top level: spec in the ascribe.toml reference.
ASC066 model-invalid-name
Error · file level · next step: write · SPEC §7.2
When: A name the content model declares, such as a dimension, a value, or a content type, breaks the rules for that kind of name.
Message: {name} isn’t a valid {role} name: {rule}
Fix: Rename it following the rule the message gives.
Read more: Names in the ascribe.toml reference.
ASC067 model-empty-text
Error · file level · next step: write · SPEC §7.2
When: A key that holds text is empty.
Message: {key} can’t be empty
Fix: Give the key a value, or remove it.
Read more: The file in the ascribe.toml reference.
ASC246 model-from-file
Error · file level · next step: write · SPEC §7.9
When: The file [from] takes from doesn’t exist, can’t be read, or is outside the project’s repository or the folder that was opened.
Message: {path}, the file [from] takes from, doesn’t exist
Fix: Fix the path after from, which is relative to the folder ascribe.toml is in, so it names the other project’s ascribe.toml, inside the project’s repository. With no repository, the editor and ascribe mcp read the file only inside the folder they were opened on: open the folder that contains it.
Read more: Taking from another project in the ascribe.toml reference.
ASC247 model-from-take
Error · file level · next step: write · SPEC §7.9
When: take names a key the other file doesn’t have, one of this project’s own, one taken twice, or something that isn’t a dotted path of keys.
Message: {file} has no {key} to take
Fix: Name a table or a key the other file has, as a dotted path of keys: releases takes the whole table, consumer.site one key. Take each once, and not a table and a key in it. spec, [project], and [from] are each project’s own, so write them in this file.
Read more: Taking from another project in the ascribe.toml reference.
ASC248 model-from-written
Error · file level · next step: write · SPEC §7.9
When: A key is taken with [from] and written in ascribe.toml too.
Message: {key} is taken from {file} and written here too; a key has one home
Fix: Delete the key here, to use the other file’s, or remove it from take, to keep this one. A table that’s taken can’t have a key of its own here: take the keys it shares instead, one by one.
Read more: Taking from another project in the ascribe.toml reference.
[project]
ASC068 model-path-absolute
Error · file level · next step: write · SPEC §2.2
When: A path in ascribe.toml is absolute, where it must be relative to ascribe.toml.
Message: {key} must be a path relative to ascribe.toml, not an absolute path
Fix: Write the path relative to the directory of ascribe.toml.
Read more: Paths and patterns in the ascribe.toml reference.
ASC069 model-content-root-missing
Error · file level · next step: write · SPEC §2.2
When: The content root doesn’t exist, or isn’t a directory.
Message: content root {path} doesn’t exist
Fix: Create the directory, or correct [project] content-root.
Read more: [project] in the ascribe.toml reference.
ASC070 model-output-overlaps-content
Error · file level · next step: write · SPEC §9.4
When: The output directory and the content root are the same, or one is inside the other.
Message: output directory {output} is inside content root {content}; move it outside, or builds will read their own output as source
Fix: Keep the output directory and the content root apart: neither inside the other, and not the same. The default output directory, .ascribe/build, is outside the default content root, docs.
Read more: [project] in the ascribe.toml reference.
[sources]
ASC133 model-source-path-missing
Error · file level · next step: write · SPEC §7.3
When: A source’s path doesn’t exist, or isn’t a folder.
Message: the folder of source {source}, {path}, doesn’t exist
Fix: Fix path, which is relative to the folder ascribe.toml is in, or create the folder.
Read more: [sources.<name>] in the ascribe.toml reference.
ASC134 model-source-outside-repository
Error · file level · next step: write · SPEC §7.3
When: A source’s folder is outside the project’s repository, or, with no repository, outside the folder that was opened.
Message: the folder of source {source}, {path}, is outside the git repository the project is in
Fix: Give the source a path inside the project’s repository, or, for code in another repository, give it git instead. With no repository, the editor and ascribe mcp read a source only inside the folder they were opened on: open the folder that contains the source.
Read more: [sources.<name>] in the ascribe.toml reference.
ASC135 model-source-remote
Error · file level · next step: write · SPEC §7.4
When: A source has both path and git, or neither, a branch without git, a URL or a branch git can’t take, or copies that would go inside the content root.
Message: source {source} has both path and git: a source is a folder in this repository or another repository, not both
Fix: Give each source either path, a folder in this repository, or git, the URL of another repository, with branch only beside git. A source with git keeps its copies in sources/<name>/, which must be outside the content root.
Read more: A source in another repository in the ascribe.toml reference.
Content types, fields, and attributes
ASC074 model-field-reserved
Error · file level · next step: write · SPEC §2.1
When: A content type, or the fragments’ frontmatter, declares a field the specification or an output reserves.
Message: {field} is reserved by the Ascribe spec and every page accepts it; remove it from [{table}]
Fix: Remove the field from the type. Every page accepts it already, with the meaning the specification gives it. Every page type has title as a required string: declare it only to set inline or phrases.
Read more: Page types in the ascribe.toml reference.
ASC075 model-type-syntax
Error · file level · next step: write · SPEC §7.2
When: A field’s or an attribute’s type isn’t one Ascribe knows, or isn’t written correctly.
Message: “{type}” isn’t a valid {kind} type: {detail}
Fix: Fix the type. The types are string, number, boolean, date, enum(a, b), list(T), and, for attributes, set(T); a ? at the end makes one optional.
Read more: Short form in the ascribe.toml reference.
ASC076 model-type-fields
Error · file level · next step: write · SPEC §7.2
When: An object field has no fields, or a field that isn’t an object has them.
Message: field {field} is an object, so it needs fields
Fix: Give an object field its fields, or remove fields from a field that isn’t an object.
Read more: Table form in the ascribe.toml reference.
ASC077 model-enum-values
Error · file level · next step: write · SPEC §7.2
When: An enumeration is empty, lists a value twice, gives its values in both places, or gives none.
Message: {field} has an empty enumeration
Fix: List the enumeration’s values once each, in enum(a, b) or in values, not both.
Read more: Short form in the ascribe.toml reference.
ASC078 model-set-token
Error · file level · next step: write · SPEC §3.3
When: A value of a set-valued attribute has a space or a reserved character.
Message: “{value}” can’t be in a value set: members can’t contain spaces or any of , | { } = “
Fix: Remove spaces and the characters , | { } = " from the value, or make the attribute a single value instead of a set.
Read more: Short form in the ascribe.toml reference.
ASC079 model-default-type
Error · file level · next step: write · SPEC §7.2
When: A field’s default isn’t of the field’s type, or isn’t one of its values.
Message: default for {field} must be {type}, but it’s {found}
Fix: Give a default of the field’s type.
Read more: Table form in the ascribe.toml reference.
ASC080 model-phrases-field-type
Error · file level · next step: write · SPEC §5.1
When: phrases = true is on a field that isn’t a string or a list(string).
Message: phrases = true only works on string and list(string) fields, and {field} is “{type}”
Fix: Remove phrases = true, or make the field a string or list(string).
Read more: [phrases] in the ascribe.toml reference.
ASC081 model-pattern-syntax
Error · file level · next step: write · SPEC §2.2
When: A pattern isn’t valid, starts with /, or has a .. segment.
Message: “{pattern}” isn’t a valid pattern: {detail}
Fix: Fix the pattern. Patterns are relative to the content root, with no leading / and no .. segment.
Read more: Paths and patterns in the ascribe.toml reference.
ASC119 model-attribute-reserved
Error · file level · next step: write · SPEC §7.2
When: An image’s or a widget’s attribute has a name that HTML or the site output already uses on its element.
Message: {key} can’t be an image attribute: HTML already uses it on the <img> element
Fix: Rename the attribute.
Read more: [images] in the ascribe.toml reference.
ASC141 model-inline-field
Error · file level · next step: write · SPEC §7.2
When: inline is on a field that isn’t a page type’s top-level string field, or isn’t "code".
Message: inline = “code” only works on string fields, and {field} is “{type}”
Fix: Remove inline, or set it to “code” on a string field of a content type’s frontmatter.
Read more: Code in a field in the ascribe.toml reference.
ASC148 model-field-role
Error · file level · next step: write · SPEC §7.2
When: A field’s role isn’t one Ascribe knows, is on a field of the wrong type or below a page type’s top level, or is on two fields of one type.
Message: role = “{role}” only works on a {expected} field, and {field} is “{type}”
Fix: Give role = "description" to one string field of a content type’s frontmatter, role = "recheck-date" to one date field, and role = "owner" to one string or enum field, or remove role. A type has at most one field with each role, and only a page type’s top-level fields have roles.
Read more: Field roles in the ascribe.toml reference.
ASC193 model-type-file
Error · file level · next step: write · SPEC §7.2
When: A content type’s template or guide doesn’t exist, or is inside the content root or the output directory, or outside the project’s folder.
Message: {path}, the {key} of content type {type}, doesn’t exist
Fix: Name a file by its path from the folder ascribe.toml is in, with its name’s case as it is on disk, outside the content root and the output directory: template = "templates/how-to.md". A type’s template and guide are read by people and tools starting a page, and aren’t pages themselves.
Read more: Page types in the ascribe.toml reference.
ASC194 model-type-template
Error · file level · next step: write · Ascribe’s own, not in SPEC
When: A content type’s template can’t be read, or isn’t a page Ascribe can read.
Message: can’t read {path}, the template of content type {type}: {reason}
Fix: Fix the template so it reads as a page: valid YAML between its --- lines, and no error in its Ascribe syntax. A template is read when the content model loads, so a problem in it is reported once, here, and not on every page made from it. A type that names no template and no guide takes them from templates/templates.lock, which ascribe templates eject writes: put back a file it gives (ascribe templates status says what’s changed), or name the type’s own template and guide.
Read more: Page types in the ascribe.toml reference.
Dimensions, names, lifecycle states, notes, and features
ASC082 model-name-multiple-roles
Error · file level · next step: write · SPEC §7.2
When: A name used in more than one role (dimension name, dimension value, lifecycle state, or feature key), or a dimension value in more than one dimension.
Message: {name} is used as both {role-a} and {role-b}; a name can have only one role, so availability specs stay unambiguous
Fix: Rename one of them, so that each name has one role.
Read more: Names in the ascribe.toml reference.
ASC083 model-name-case
Warning · file level · next step: write · SPEC §7.2
When: Two names the content model declares differ only in case.
Message: {a} and {b} differ only in case; names are case-sensitive, so they’re easy to confuse
Fix: Rename one of them, so they differ by more than case.
Read more: Names in the ascribe.toml reference.
ASC084 model-dimension-empty
Error · file level · next step: write · SPEC §7.2
When: A dimension has no values.
Message: dimension {dimension} has no values
Fix: Add the dimension’s values, or remove the dimension.
Read more: [dimensions.<name>] in the ascribe.toml reference.
ASC085 model-dimension-value-duplicate
Error · file level · next step: write · SPEC §7.2
When: A dimension lists a value twice.
Message: {value} appears twice in dimensions.{dimension}.values
Fix: Remove the repeated value.
Read more: [dimensions.<name>] in the ascribe.toml reference.
ASC086 model-dimension-value-shared
Error · file level · next step: write · SPEC §7.2
When: A value is in more than one dimension.
Message: {value} is a value of both {a} and {b}; a value can belong to only one dimension
Fix: Rename the value in one of the dimensions.
Read more: [dimensions.<name>] in the ascribe.toml reference.
ASC087 model-label-undeclared
Error · file level · next step: choose · SPEC §7.2
When: A dimension’s labels gives a label for a value the dimension doesn’t have.
Message: dimensions.{dimension}.labels has a label for {value}, which isn’t one of its values: {values}
Fix: Correct the label’s key, or add the value to the dimension’s values.
Read more: [dimensions.<name>] in the ascribe.toml reference.
ASC088 model-versionless-undeclared
Error · file level · next step: choose · SPEC §7.2
When: A dimension’s versionless lists a value the dimension doesn’t have.
Message: dimensions.{dimension}.versionless lists {value}, which isn’t one of its values: {values}
Fix: Correct the entry, or add the value to the dimension’s values.
Read more: [dimensions.<name>] in the ascribe.toml reference.
ASC089 model-lifecycle-available-required
Error · file level · next step: choose · SPEC §7.2
When: A lifecycle state the project adds doesn’t say whether it counts as available.
Message: new lifecycle state {state} must set available = true or available = false
Fix: Add available = true or available = false to the state.
Read more: [lifecycle.<state>] in the ascribe.toml reference.
ASC090 model-lifecycle-ga-unavailable
Error · file level · next step: write · SPEC §7.2
When: [lifecycle.ga] doesn’t count as available.
Message: ga must count as available: content with no lifecycle state is ga
Fix: Remove available = false from [lifecycle.ga].
Read more: [lifecycle.<state>] in the ascribe.toml reference.
ASC091 model-note-label-required
Error · file level · next step: write · SPEC §4.5
When: A note type the project adds has no label.
Message: new note type {type} needs a label, such as label = “{Type}”
Fix: Give the note type a label.
Read more: [notes.<type>] in the ascribe.toml reference.
ASC092 model-availability-syntax
Error · file level · next step: write · SPEC §4.4
When: A feature’s available isn’t a valid availability spec.
Message: feature {key}: “{spec}” isn’t a valid availability spec: {detail}
Fix: Fix the feature’s available spec. Its syntax is in the directive reference.
Read more: [features.<key>] in the ascribe.toml reference.
ASC093 model-availability-unknown-name
Error · file level · next step: choose · SPEC §4.4
When: A feature’s available names a target or a state the content model doesn’t declare.
Message: feature {key}: {name} isn’t a declared dimension value or dimension name
Fix: Use a declared dimension value, dimension, or lifecycle state, or declare the name.
Read more: [features.<key>] in the ascribe.toml reference.
ASC094 model-availability-versionless
Error · file level · next step: write · SPEC §4.4
When: A feature’s available gives a version to a versionless target or a dimension name.
Message: feature {key}: {target} is versionless, so it takes a state but no version
Fix: Remove the version. A versionless target, or a dimension name, takes a state but no version.
Read more: [features.<key>] in the ascribe.toml reference.
ASC095 model-availability-history-order
Error · file level · next step: write · SPEC §4.4
When: A feature’s history for a target isn’t in chronological order.
Message: feature {key}: the history for {target} must be in chronological order, but {later} comes before {earlier}
Fix: List the target’s states oldest first.
Read more: [features.<key>] in the ascribe.toml reference.
ASC096 model-feature-nested
Error · file level · next step: write · SPEC §4.4
When: A feature’s available names another feature.
Message: feature {key}: available must be an availability spec, not another feature ({other})
Fix: Write the feature’s availability out in full. One feature can’t refer to another.
Read more: [features.<key>] in the ascribe.toml reference.