Diagnostics: the content model's builds and site
The diagnostics about releases, phrases, widgets, the consumer, builds, the editor, permalinks, crawlers, listing, and checks in ascribe.toml, 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’s [releases], phrases, widgets, consumer, builds, and editor, and in [permalinks], [crawlers], [listing], and [checks]. One that’s an error stops everything else: every other check depends on the content model. The rest of the content model’s diagnostics, from the file to its names, are on Diagnostics: the content model. Part of the diagnostics reference, which says what an entry’s severity, level, and next step mean, and has an index of every diagnostic.
[releases]
ASC204 model-releases-target
Error · file level · next step: choose · SPEC §7.2
When: A [releases] table names a target that’s versionless, a dimension, or a name [dimensions.release] takes, or labels a target its dimension labels.
Message: [releases.{target}]: {target} is in no declared dimension, so it would be a value of the implicit dimension release, but [dimensions.release] takes that name; add {target} to a dimension’s values, or rename [dimensions.release]
Fix: Name the table after the target a mark gives a version to, such as [releases.self-managed]: a versioned value of a declared dimension, or a name no dimension has, which makes it a value of the implicit dimension release. A versionless value has no versions to list. While a target is left to the implicit dimension, no declared dimension can be named release.
Read more: [releases.<target>] in the ascribe.toml reference.
ASC205 model-releases-line
Error · file level · next step: write · SPEC §7.2
When: A target’s lines in [releases] aren’t valid versions, are listed twice, or have different numbers of parts.
Message: [releases.{target}] mixes lines of different lengths, {a} and {b}; write every line of a target with the same number of parts
Fix: Write each line as a version, once, with as many parts as the target’s other lines: ["3.4", "3.5"] for a line for each minor release, or ["0.2.0"] for one for each patch release. A line holds every version that starts with it.
Read more: [releases.<target>] in the ascribe.toml reference.
ASC207 model-releases-order
Error · file level · next step: write · SPEC §7.2
When: A target’s planned line isn’t newer than every live line, an archived line isn’t older than every live one, or a line is in two lists.
Message: [releases.{target}]: the planned line {line} isn’t newer than every live line, and the newest is {live}
Fix: Keep each line in one list, in the order the lists mean: planned lines are newer than every live line, and archived lines older. A line that has shipped moves from planned to live, and one that has left the window from live to archived.
Read more: [releases.<target>] in the ascribe.toml reference.
ASC208 model-releases-ends
Error · file level · next step: choose · SPEC §7.2
When: [releases.<target>.ends] gives an end date to a line that isn’t live.
Message: [releases.{target}.ends]: {line} isn’t a live line; the live lines are {live}
Fix: Give an end date to a line in live only. A line whose support has ended and that has left the window goes in archived, with its date as ended.
Read more: [releases.<target>] in the ascribe.toml reference.
ASC209 model-versions-current
Error · file level · next step: write · SPEC §7.2
When: ascribe.toml has [versions] current, which is no longer a key.
Message: [versions] current is no longer a key; a target’s current release is the newest line in [releases.<target>] live
Fix: Remove current from [versions], and list the release in [releases.<target>], as live = ["3.4"], for the target it’s a release of. Each target has its own current line, and a check that compared with current, availability-left-behind, compares each target’s versions with that target’s current line.
Read more: [releases.<target>] in the ascribe.toml reference.
Phrases and the glossary
ASC097 model-phrase-value-type
Error · file level · next step: write · SPEC §5.1
When: A phrase’s value isn’t a string, or a table naming a target’s line.
Message: phrase {key} must be a quoted string, but it’s {found}; write {key} = “{value}”
Fix: Quote the value. A phrase whose value is a target’s current release line is a table with one key, line: release = { line = "self-managed" }.
Read more: [phrases] in the ascribe.toml reference.
ASC215 model-phrase-line
Error · file level · next step: choose · SPEC §5.1
When: A phrase is the line of a target that has no live line.
Message: phrase {key} is the line of {target}, which has no live line in [releases]
Fix: Name a target whose lines [releases.<target>] lists, with at least one in live, or list the target’s lines there. The phrase is the target’s current line: the newest live one.
Read more: [phrases] in the ascribe.toml reference.
ASC238 model-glossary-page
Error · file level · next step: choose · SPEC §7.2
When: A path in [glossary] pages doesn’t exist, or is a fragment.
Message: {path} in [glossary] pages doesn’t exist
Fix: Each path in pages is a page, from the content root, with its name’s case as it is on disk: fix the path, or, for a fragment, list a page that includes it.
Read more: [glossary] in the ascribe.toml reference.
Widgets
ASC100 model-widget-reserved-name
Error · file level · next step: write · SPEC §6
When: A widget’s name is reserved by Ascribe’s element library or by HTML.
Message: widget name {name} is reserved: names starting with ascribe- belong to Ascribe’s element library
Fix: Rename the widget, for example with your project’s name as its prefix: quill-aside.
Read more: [widgets.<name>] in the ascribe.toml reference.
ASC101 model-widget-forms
Error · file level · next step: choose · SPEC §6
When: A widget’s forms isn’t one of the lists it allows.
Message: forms must be [“line”], [“container”], or [“line”, “container”]
Fix: Set forms to ["line"], ["container"], or ["line", "container"].
Read more: [widgets.<name>] in the ascribe.toml reference.
ASC102 model-widget-binding
Error · file level · next step: choose · SPEC §6
When: A widget with a line form has no binding, or a container-only widget has one.
Message: widget {name} has a line form, so it needs a binding: “self”, “heading”, “block”, or “heading-or-block”
Fix: Give a widget with a line form a binding. Remove binding from a container-only widget.
Read more: [widgets.<name>] in the ascribe.toml reference.
ASC103 model-widget-container-primary
Error · file level · next step: write · SPEC §6
When: A widget with a container form requires a primary, or a container-only widget takes one.
Message: widget {name} has a container form, whose opener has no primary, so its primary can’t be required; use “{kind}?”
Fix: Make the primary optional ("text?"), or remove the widget’s container form. A container-only widget takes no primary.
Read more: [widgets.<name>] in the ascribe.toml reference.
ASC104 model-widget-groupable-form
Error · file level · next step: write · SPEC §6
When: A groupable widget has a line form.
Message: widget {name} is groupable, so it must be container-only: forms = [“container”]
Fix: Set forms = ["container"], or remove groupable.
Read more: [widgets.<name>] in the ascribe.toml reference.
ASC105 model-widget-plain-content
Error · file level · next step: write · SPEC §6
When: A widget that doesn’t wrap content sets plain-content.
Message: widget {name} doesn’t wrap content, so plain-content has no effect; remove it
Fix: Remove plain-content.
Read more: [widgets.<name>] in the ascribe.toml reference.
The consumer, builds, and the editor
ASC106 model-consumer-unsupported
Error · file level · next step: choose · SPEC §9.5
When: A [consumer] key has a value the consumer profile doesn’t support.
Message: the {profile} profile doesn’t support {key} = {value}; use {values}
Fix: Use one of the values the message lists.
Read more: [consumer] in the ascribe.toml reference.
ASC107 model-consumer-site
Error · file level · next step: write · SPEC §9.5
When: [consumer] site isn’t an origin alone, such as https://docs.example.com.
Message: site must be an origin such as “https://docs.example.com”; put any path in base-path
Fix: Set site to the origin alone, such as "https://docs.example.com", and put any path in base-path.
Read more: [consumer] in the ascribe.toml reference.
ASC108 model-consumer-base-path
Error · file level · next step: write · SPEC §9.5
When: [consumer] base-path doesn’t start with /.
Message: base-path must start with “/”, such as “/docs/”
Fix: Start base-path with /: "/docs/".
Read more: [consumer] in the ascribe.toml reference.
ASC109 model-build-name-case
Error · file level · next step: write · SPEC §9.3
When: Two builds’ names differ only in case.
Message: builds {a} and {b} differ only in case, so they’d share an output directory on some file systems
Fix: Rename one of the builds.
Read more: [builds.<name>] in the ascribe.toml reference.
ASC110 model-build-variants
Error · file level · next step: write · SPEC §9.3
When: A build’s variants isn’t "switch" or a selection that names a dimension.
Message: variants must be “switch” or a selection such as { deployment = “cloud” }
Fix: Set variants to "switch", or to a selection that names at least one dimension.
Read more: [builds.<name>] in the ascribe.toml reference.
ASC111 model-build-unknown-dimension
Error · file level · next step: choose · SPEC §9.3
When: A build’s selection names a dimension the content model doesn’t declare.
Message: build {build} selects dimension {dimension}, which isn’t declared
Fix: Correct the dimension’s name, or declare the dimension in [dimensions].
Read more: [builds.<name>] in the ascribe.toml reference.
ASC112 model-build-unknown-value
Error · file level · next step: choose · SPEC §9.3
When: A build’s selection names a value its dimension doesn’t have.
Message: build {build}: {value} isn’t a value of {dimension}; values: {values}
Fix: Use one of the values the message lists.
Read more: [builds.<name>] in the ascribe.toml reference.
ASC113 model-build-availability
Error · file level · next step: write · SPEC §9.3
When: A build’s availability isn’t "badge" or a filter.
Message: availability must be “badge” or { filter = “<target> <version>” }
Fix: Set availability to "badge", or to { filter = "<target> <version>" }.
Read more: [builds.<name>] in the ascribe.toml reference.
ASC114 model-build-filter-target
Error · file level · next step: choose · SPEC §9.3
When: A build’s filter names something other than a declared dimension value.
Message: build {build} filters for {target}, which isn’t a declared dimension value
Fix: Filter for a declared dimension value, not a dimension name.
Read more: [builds.<name>] in the ascribe.toml reference.
ASC115 model-build-filter-version
Error · file level · next step: write · SPEC §9.3
When: A build’s filter gives a versioned target no version, a versionless one a version, or a version that isn’t valid.
Message: build {build} filters for {target}, which is versioned, so it needs a version, such as “{target} 3.3”
Fix: Give a versioned target a version ("self-managed 3.3"), and a versionless target none.
Read more: [builds.<name>] in the ascribe.toml reference.
ASC116 model-build-filter-excluded
Warning · file level · next step: write · SPEC §9.3
When: A build filters for a target its own selection of variants leaves out.
Message: build {build} filters for {target}, but its selection keeps only {dimension} = {values}, so pages marked for {target} are dropped
Fix: Make the build’s variants selection keep the target it filters for, or filter for a target it keeps.
Read more: [builds.<name>] in the ascribe.toml reference.
ASC117 model-editor-build-unknown
Error · file level · next step: choose · SPEC §10
When: [editor] build names a build the content model doesn’t declare.
Message: editor.build is {build}, which isn’t a declared build; builds: {builds}
Fix: Set [editor] build to one of the builds the message lists.
Read more: [editor] in the ascribe.toml reference.
ASC118 model-editor-build-required
Error · file level · next step: choose · SPEC §10
When: The content model declares several builds, none named site, and [editor] build doesn’t name one.
Message: there are several builds and none is named site; set [editor] build to the one the editor should check
Fix: Set [editor] build to the build the editor should check, or name one of the builds site.
Read more: [editor] in the ascribe.toml reference.
ASC162 model-consumer-agents-site
Error · file level · next step: write · SPEC §9.5
When: [consumer] agents = true without [consumer] site.
Message: agents = true needs site: every link in llms.txt and the Markdown pages is an absolute URL
Fix: Set site in [consumer] to the published site’s origin, such as "https://docs.example.com", or remove agents.
Read more: [consumer] in the ascribe.toml reference.
ASC174 model-consumer-permalink-path
Error · file level · next step: write · SPEC §9.5
When: [consumer] permalink-path doesn’t start with /.
Message: permalink-path must start with “/”, such as “/go/”
Fix: Start permalink-path with /: "/go/". It’s a path from the site’s root, not from base-path.
Read more: [consumer] in the ascribe.toml reference.
ASC206 model-build-versions
Error · file level · next step: write · SPEC §9.3
When: A versioned build’s target has no live line, or the build is filtered too.
Message: build {build} is versioned by {target}, which has no live line; list its lines in [releases.{target}], such as live = ["3.4"]
Fix: Give the target its lines in [releases.<target>], with live, or remove versions from the build. A build is either versioned, with one output for each live line, or filtered for one version; not both.
Read more: [builds.<name>] in the ascribe.toml reference.
[crawlers]
ASC183 model-crawlers-line
Error · file level · next step: write · SPEC §7.2
When: A string in [crawlers] lines has a line break.
Message: {key} has a line break; each string in lines is one line of robots.txt
Fix: Split the string into one string per line: lines = ["User-agent: *", "Disallow: /drafts/"].
Read more: [crawlers] in the ascribe.toml reference.
ASC189 model-crawlers-named-twice
Error · file level · next step: write · SPEC §7.2
When: [crawlers] names one crawler in two groups.
Message: {key} names {token}, which a group on line {line} names already; a crawler obeys only one group, so write everything for it in one
Fix: Name each crawler in one group. Move the lines for it into the first group that names it and remove the second User-agent line. For a crawler a disallowed purpose covers, the purpose’s group already says Disallow: /: remove the group from lines, or allow the purpose and write the crawler’s group whole in lines.
Read more: [crawlers] in the ascribe.toml reference.
[listing]
ASC185 model-listing-folder
Error · file level · next step: write · SPEC §7.2
When: A folder in [listing.folders] doesn’t exist, isn’t a folder, or isn’t written as a folder’s path.
Message: {folder} in [listing.folders] doesn’t exist under the content root
Fix: Write the folder’s path from the content root, ending in /, with its name’s case as it is on disk: "internal/" = "unlisted". A rule is for a folder and everything under it; patterns aren’t read.
Read more: [listing] in the ascribe.toml reference.
ASC186 model-listing-type
Error · file level · next step: choose · SPEC §7.2
When: [listing.types] names something that isn’t a content type.
Message: {type} in [listing.types] isn’t a content type; use one of: {values}
Fix: Name a content type the project declares in [types], or page when it declares none.
Read more: [listing] in the ascribe.toml reference.
ASC187 model-listing-looser
Error · file level · next step: write · SPEC §7.2
When: A rule of [listing] is looser than a wider rule it’s under.
Message: {rule} is looser than {wider} on line {line}, which it’s under; a narrower rule can only restrict
Fix: Remove the narrower rule, or make it as strict as the one it’s under, or stricter: listed, then unquoted, then unlisted. To list some pages more openly than the rest, loosen the wider rule, and restrict the others with rules of their own.
Read more: [listing] in the ascribe.toml reference.
[apis]
ASC259 model-api-outside-repository
Error · file level · next step: write · SPEC §7.11
When: An API’s spec is outside the project’s repository, or, with no repository, outside the folder that was opened.
Message: the spec of API {api}, {path}, is outside the git repository the project is in
Fix: Give the API a spec inside the project’s repository: a spec in another repository isn’t read, so commit a copy of it, or the file your pipeline bundles. With no repository, the editor and ascribe mcp read a spec only inside the folder they were opened on: open the folder that contains it.
Read more: [apis.<name>] in the ascribe.toml reference.
ASC260 model-api-reference
Error · file level · next step: write · SPEC §7.11
When: An API’s reference is an address pattern with a placeholder other than {operationId} and {tag}, or with no {operationId}.
Message: the reference of API {api} has no {operationId}, so every operation’s address would be the same
Fix: Write the address pattern as your renderer addresses an operation, with {operationId} where the operation’s id goes and {tag} for its first tag, such as "/api/#/operations/{operationId}" for Stoplight Elements. For Redoc, write { renderer = "redoc", at = "/api/" } instead.
Read more: [apis.<name>] in the ascribe.toml reference.
[checks]
ASC142 model-check-not-configurable
Error · file level · next step: write · SPEC §8.2
When: [checks] sets the level of a check about whether the project is valid.
Message: {check} can’t be set in [checks]: it reports whether the project is valid, which a project can’t lower or turn off
Fix: Remove the check from [checks]. Only checks about the content’s quality, which the diagnostics reference marks as configurable, can be set there; a diagnostic about whether the project is valid is always reported at its own severity.
Read more: [checks] in the ascribe.toml reference.
ASC146 model-intended-check
Error · file level · next step: choose · SPEC §4.9
When: An acknowledgement in [[intended]] names something that isn’t a check, a check that isn’t a review check, or one whose problems are acknowledged in the pages.
Message: {check} isn’t a check
Fix: Name a check whose next step is review and whose problems are about a phrase, feature, glossary term, or image, by its name in the diagnostics reference. A page’s or a block’s problem is acknowledged in the page itself.
Read more: [[intended]]: acknowledgements in the ascribe.toml reference.
ASC147 model-intended-entry
Error · file level · next step: choose · SPEC §4.9
When: An acknowledgement in [[intended]] doesn’t name exactly one thing the content model declares, or its reason is still a placeholder.
Message: an acknowledgement in [[intended]] names what it’s about with one of phrase, feature, or image
Fix: Give the acknowledgement exactly one of phrase, feature, or image (a path under the content root), naming something the content model declares, and a reason of your own in place of the placeholder the editor’s quick fix writes.
Read more: [[intended]]: acknowledgements in the ascribe.toml reference.
ASC167 model-checks-vale
Error · file level · next step: write · SPEC §8.2
When: [checks.vale] has both preset and config, or neither, or turns off a rule with config or one its preset doesn’t have.
Message: [checks.vale] has both preset and config; pick one: Ascribe’s preset, or the project’s own .vale.ini
Fix: Give [checks.vale] one of preset = "quiet" or config = "<path to .vale.ini>". off lists rules of the preset to turn off, by their names in alerts (Ascribe.Repeated), and is only for a preset.
Read more: [checks.vale] in the ascribe.toml reference.