Diagnostics: directives
The diagnostics about attributes, directives, containers, binding, titles, ids, includes, variants, availability, steps, details, and widgets.
For AI agents: the documentation index is at llms.txt, and this page is available as Markdown.
The problems Ascribe reports in a source file’s directives and their attributes: what each binds to, and the rules of each built-in directive and project widget. Part of the diagnostics reference, which says what an entry’s severity, level, and next step mean, and has an index of every diagnostic.
Attributes
ASC001 attribute-unknown-key
Error · file level · next step: choose · SPEC §3.3
When: Unknown key for the directive, image, or table row.
Message: @{name} has no attribute {key}; its attributes are: {keys}
Fix: Fix the key’s spelling, or remove it. To accept a new image attribute, declare it in [images.attributes]; for a project widget, in its attributes.
Read more: Attributes in the directive syntax reference.
ASC002 attribute-type-mismatch
Error · file level · next step: choose · SPEC §3.3
When: Value doesn’t match the key’s declared type.
Message: {key} must be {expected}, but it’s “{value}”
Fix: Give a value of the key’s declared type: one of the enumeration’s values, true or false for a boolean, or a plain number such as 600 for a number.
Read more: Attributes in the directive syntax reference.
ASC003 attribute-bare-key
Error · file level · next step: write · SPEC §3.3
When: Bare key without a value.
Message: {key} needs a value, such as {key}=<value>; booleans are written out too: {key}=true
Fix: Give the key a value: key=value. Booleans are written out too: open=true.
Read more: Attributes in the directive syntax reference.
ASC004 attribute-unquoted-reserved
Error · file level · next step: fix · SPEC §3.3
When: Unquoted value containing a reserved character.
Message: the value of {key} contains {character}, so it must be quoted: {key}="{value}"
Fix: Quote the value: label="Using other images".
Read more: Attributes in the directive syntax reference.
ASC055 attribute-syntax
Error · file level · next step: write · SPEC §3.3
When: Attribute block that doesn’t parse (such as an unclosed quote or brace, or = with no value).
Message: this attribute block isn’t valid: {detail}
Fix: Fix the attribute block: close every quote and brace, give every = a value, and separate pairs with commas.
Read more: Attributes in the directive syntax reference.
ASC056 attribute-duplicate-key
Error · file level · next step: write · SPEC §3.3
When: The same key given more than once.
Message: {key} is given more than once; give each attribute once
Fix: Give the key once. For several values of a set-valued key, write a value set: platform=cloud|on-prem.
Read more: Attributes in the directive syntax reference.
ASC284 info-pair-malformed
Warning · file level · next step: write · SPEC §3.3.1
When: A word after a fenced code block’s language that starts like a pair a processor reads (its key in any case, then optional spaces and =) but isn’t one.
Message: {written} starts like the pair {key} but isn’t one, so it isn’t read; write {key}= with nothing around =, then the value, in double quotes if it has a space or a quote
Fix: Write the pair as SPEC §3.3.1 reads it: the key in lowercase, = with nothing around it, and the value, in double quotes when it has a space or a quote. Inside the quotes, write a quote as \\" and a backslash as \\\\ in the page, since CommonMark takes one backslash off before the pair is read. A word that isn’t meant as a pair can’t start with phrases, title, tested, request, or response and =.
Read more: Code block info strings in the directive syntax reference.
Directives
ASC005 directive-unknown
Warning · file level · next step: choose · SPEC §3.2
When: Directive-shaped line (@word followed by {, :, or end of line) with an unknown name.
Message: @{name} isn’t a known directive, so this line is text; write \@{name} if that’s what you mean
Fix: Correct the directive’s name, or declare a project widget with that name in ascribe.toml. If the line is meant as text, write \@ at its start.
Read more: Directive lines in the directive syntax reference.
ASC006 directive-primary
Error · file level · next step: write · SPEC §3.4
When: Primary given to a directive that takes none, or a required primary missing.
Message: @{name} doesn’t take a primary; remove the text after its colon
Fix: Remove the text after the colon, or add the primary the directive needs, such as the path in @include: setup.md.
Read more: Directive lines in the directive syntax reference.
ASC120 directive-extra-text
Error · file level · next step: fix · SPEC §3.1
When: Text on a directive line that fits no part of it: after the name or attributes, after @end, or after an identifier primary.
Message: @{name}’s primary is a single word, so {extra} isn’t part of it; remove it
Fix: Put attributes in braces, as in @note {type=warning}: text. Remove any other extra text: text a directive should show belongs in its primary, after the colon, or in its content.
Read more: Directive lines in the directive syntax reference.
Container
ASC007 container-unclosed
Error · file level · next step: write · SPEC §3.5
When: Container not closed before its enclosing block ends.
Message: the @{name} container opened here isn’t closed before {end}; add @end where it should end
Fix: Add an @end line where the container’s content ends, indented like its opener.
Read more: Forms: line and container in the directive syntax reference.
ASC008 container-colon-unexpected
Error · file level · next step: fix · SPEC §3.5
When: Trailing : on a directive with no container form.
Message: @{name} has no container form, so its line can’t end in a colon; remove the trailing :
Fix: Remove the trailing colon. The directive applies to what its binding says, such as the block after it.
Read more: Forms: line and container in the directive syntax reference.
ASC009 container-colon-missing
Error · file level · next step: fix · SPEC §3.5
When: Container-only directive without a trailing :.
Message: @{name} is always a container; end its line with a colon to open it
Fix: End the opener’s line with a colon, and close the container with @end.
Read more: Forms: line and container in the directive syntax reference.
ASC010 container-open-at-arm
Error · file level · next step: write · SPEC §3.6
When: Container still open when the next arm of its group begins (reported at that arm’s opener).
Message: the @{name} container opened on line {line} is still open where this @{group} arm begins; close it with @end first
Fix: Close the inner container with @end before the next arm’s opener.
Read more: Groups in the directive syntax reference.
ASC011 end-unmatched
Error · file level · next step: write · SPEC §3.5
When: End line with no open container.
Message: this @end has no open container to close; if a directive above should be a container, end its line with a colon
Fix: Remove the @end, or make the directive it should close a container by ending that directive’s line with a colon.
Read more: Forms: line and container in the directive syntax reference.
ASC012 end-indent-mismatch
Error · file level · next step: write · SPEC §3.9
When: End line indented differently from its opener.
Message: this @end is indented differently from the @{name} it would close; indent them the same
Fix: Indent the @end exactly as its opener is indented.
Read more: Lists and block quotes in the directive syntax reference.
ASC013 container-nesting-deep
Warning · file level · next step: write · SPEC §3.10
When: Nesting deeper than two levels.
Message: containers are nested {depth} levels deep here; more than two is hard to follow, so flatten them, for example with a following-block form
Fix: Flatten the structure: use a directive’s following-block form instead of a container, or split the content into sections.
Read more: Forms: line and container in the directive syntax reference.
Binding
ASC014 binding-no-block
Error · file level · next step: write · SPEC §3.8
When: Following-block directive with no following block in its container.
Message: @{name} applies to the block after it, but nothing follows it in this {container}
Fix: Put the block the directive applies to directly below it, in the same container, or remove the directive.
Read more: Binding: what a directive applies to in the directive syntax reference.
ASC015 binding-heading
Error · file level · next step: write · SPEC §3.8
When: Following-block directive bound to a heading.
Message: @{name} applies to the next block, and the next block here is a heading; a directive can’t be bound to a heading
Fix: Move the directive below the heading, directly above the block it describes.
Read more: Binding: what a directive applies to in the directive syntax reference.
ASC016 binding-blank-line
Warning · file level · next step: fix · SPEC §3.8
When: Blank line between a following-block directive and its block.
Message: a blank line separates @{name} from the block it applies to; remove it so the directive touches its block
Fix: Remove the blank line, so the directive touches its block. ascribe fmt does this.
Read more: Binding: what a directive applies to in the directive syntax reference.
ASC017 binding-not-section-top
Error · file level · next step: write · SPEC §3.8
When: Heading-bound directive that isn’t at the top of its section.
Message: @{name} applies to its heading’s section, so it must come directly under the heading, before any other content
Fix: Move the directive directly under its heading, before any other content of the section.
Read more: Binding: what a directive applies to in the directive syntax reference.
Title
ASC018 title-not-accepted
Warning · file level · next step: write · SPEC §3.7
When: Title given to a directive that doesn’t accept one.
Message: this line looks like a title, but @{name} below it doesn’t take one, so it’s text; if that’s intended, start it with \. to silence this
Fix: Remove the title line, or start it with \. if it’s text that begins with a dot.
Read more: Titles in the directive syntax reference.
ASC019 title-dot-space
Warning · file level · next step: write · SPEC §3.7
When: A . line (dot and space) directly above a directive that accepts a title.
Message: a title line has no space after its dot; write .{title} to make this the title of the @{name} below
Fix: Remove the space after the dot (.Title) to make the line a title, or separate it from the directive with a blank line if it’s text.
Read more: Titles in the directive syntax reference.
@id
ASC020 id-duplicate
Error · page level · next step: write · SPEC §4.1
When: Duplicate id on a page, including ids from included content.
Message: the id {id} is used more than once on this page; every id on a page must be unique
Fix: Give one of the headings a different @id. When the second id comes from an included fragment, change it in the page or in the fragment, or include the fragment once.
Read more: @id in the directive reference.
ASC058 id-invalid
Error · file level · next step: write · SPEC §4.1
When: Id, or a page’s permalink, containing characters other than letters, digits, hyphens, underscores, and periods.
Message: {id} isn’t a valid id: use only letters, digits, hyphens, underscores, and periods
Fix: Use only letters, digits, hyphens, underscores, and periods in the id, or in the page’s permalink.
Read more: @id in the directive reference.
ASC173 permalink-duplicate
Error · page level · next step: write · SPEC §4.1
When: Permalink published by one build in more than one place, names compared ignoring case: on two pages, or as a page’s own and a heading’s.
Message: the permalink {name} is also on {page}; a build can publish each permalink in one place only
Fix: Give one of them a different name (a heading’s @id, or a page’s permalink), or stop it being a permalink: remove {permalink=true} from the @id, or permalink from the frontmatter. When the permalink is in a fragment that several pages include, mark the heading in one page instead, or make sure no build publishes two of those pages.
Read more: Permalinks in the directive reference.
@include
ASC021 include-target-missing
Error · file level · next step: choose · SPEC §4.2
When: Target file doesn’t exist.
Message: the included file {path} doesn’t exist
Fix: Fix the path. It’s relative to the including file, or to the content root when it starts with /, and the file must be a Markdown source file inside the content root.
Read more: @include in the directive reference.
ASC022 include-id-missing
Error · page level · next step: choose · SPEC §4.2
When: Target id doesn’t exist in the target file.
Message: {path} has no heading with the id {id}
Fix: Fix the #id, or give the heading you want to include that id with @id.
Read more: @include in the directive reference.
ASC023 include-cycle
Error · page level · next step: write · SPEC §4.2
When: Include cycle.
Message: including {path} here creates a cycle: {cycle}
Fix: Remove one of the includes in the cycle. A section can’t include itself, directly or through other files.
Read more: @include in the directive reference.
ASC125 include-heading-without-id
Warning · file level · next step: write · SPEC §4.2
When: {heading=false} without an #id, which has no effect.
Message: heading=false only applies to an include of a section (file.md#id), so it does nothing here; remove it, or name the section
Fix: Remove heading=false, or include a section: file.md#id.
Read more: @include in the directive reference.
ASC182 include-limit
Error · page level · next step: write · SPEC §4.2
When: A page’s includes expand it past the processor’s limit.
Message: including {path} here takes this page past {limit}, the most a page’s includes may expand it to; it isn’t expanded, and no include after it is
Fix: Include less on this page. Usually a fragment is included more than once on the way: a few files that each include the next twice double the page at every step. Include each fragment once, or split the page.
Read more: @include in the directive reference.
@variant
ASC024 variant-no-arm-survives
Warning · page level · next step: write · SPEC §9.3
When: No arm of a group survives a build’s selection.
Message: build {build} removes every arm of this @variant group, so none of its content is published in that build
Fix: Add an arm for the build’s selection, or check the build’s variants in ascribe.toml. If the content is meant to be absent from that build, the warning can be ignored.
Read more: @variant in the directive reference.
ASC025 variant-unknown
Error · file level · next step: choose · SPEC §4.3
When: Unknown dimension or value.
Message: {dimension} isn’t a declared dimension; the dimensions are: {dimensions}
Fix: Use a dimension and value declared in [dimensions], or declare them there: [dimensions.<name>] with values = ["<value>", …].
Read more: @variant in the directive reference.
ASC026 variant-mixed-arms
Error · file level · next step: write · SPEC §4.3
When: Group mixes labeled and dimensional arms.
Message: this group mixes labeled and dimensional arms; give every arm attributes, or every arm a title
Fix: Make every arm of the group dimensional (attributes, such as {pm=npm}) or every arm labeled (a title line).
Read more: @variant in the directive reference.
ASC027 variant-arm-kind
Error · file level · next step: write · SPEC §4.3
When: Arm has both a title and attributes, or neither.
Message: this @variant arm has both a title and attributes; use one or the other
Fix: Give the arm either attributes or a title line: one, not both and not neither.
Read more: @variant in the directive reference.
ASC028 variant-no-shared-dimension
Error · file level · next step: write · SPEC §4.3
When: Dimensional arms share no dimension key.
Message: the arms of this group have no dimension in common; every arm must name at least one of the same dimensions
Fix: Name at least one dimension that every arm of the group shares.
Read more: @variant in the directive reference.
@available
ASC029 available-unknown
Error · file level · next step: choose · SPEC §4.4
When: Unknown target or state.
Message: {name} isn’t a declared dimension value, dimension, or feature key
Fix: Use a declared dimension value, dimension, feature key, or lifecycle state, or declare the name in ascribe.toml.
Read more: @available in the directive reference.
ASC030 available-history-order
Error · file level · next step: write · SPEC §4.4
When: History out of chronological order.
Message: the history for {target} must be in chronological order, but {later} comes before {earlier}
Fix: List the target’s states oldest first: self-managed (preview 3.3, ga 3.5).
Read more: Availability specs in the directive reference.
ASC031 available-versionless
Error · file level · next step: write · SPEC §4.4
When: Versions given for a versionless target.
Message: {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: cloud beta.
Read more: Availability specs in the directive reference.
ASC032 available-exceeds-scope
Error · page level · next step: write · SPEC §4.4
When: Spec exceeds its enclosing scope.
Message: this availability includes {target}, which the enclosing {scope} doesn’t
Fix: Narrow this availability to what the enclosing page or section allows, or widen the enclosing one.
Read more: @available in the directive reference.
ASC057 available-syntax
Error · file level · next step: write · SPEC §4.4
When: Spec that doesn’t parse, in a directive or in available frontmatter.
Message: “{spec}” isn’t a valid availability spec: {detail}
Fix: Fix the availability spec. Its syntax is in the directive reference.
Read more: Availability specs in the directive reference.
ASC210 available-version-ahead
Error · file level · next step: choose · SPEC §4.4
When: Version newer than every release line its target declares.
Message: {version} is newer than every line [releases.{target}] declares, and the newest is {newest}
Fix: Correct the number to a declared line, such as the newest, or, for a line that’s planned, add it to planned in [releases.<target>]. Work for the planned line is marked with planned in place of its number, as <target> planned, and ascribe versions release writes the number when the line ships.
Read more: [releases.<target>] in the ascribe.toml reference.
ASC245 available-planned-line
Error · file level · next step: write · SPEC §4.4
When: planned for a target with no planned line, or more than one.
Message: {target} has no planned line, so planned names no version; declare one in [releases.{target}] planned, or write the version
Fix: Write the version in place of planned, or, for work in a line that hasn’t shipped, declare that line in [releases.<target>] planned. planned names a target’s planned line, so it needs exactly one: with two, write the version of the one the content is in.
Read more: The planned line in the directive reference.
@steps
ASC033 steps-not-ordered-list
Error · file level · next step: write · SPEC §4.6
When: Bound block isn’t an ordered list.
Message: @steps must be followed by an ordered list (1., 2., …), but the next block is {found}
Fix: Put an ordered list directly below @steps.
Read more: @steps in the directive reference.
@details
ASC034 details-title-missing
Error · file level · next step: write · SPEC §4.7
When: Missing title.
Message: @details needs a title line directly above it: the text readers see while the content is collapsed
Fix: Add a title line directly above @details: .Show the full configuration.
Read more: @details in the directive reference.
Project widget
ASC035 widget-schema
Error · file level · next step: write · SPEC §6
When: Violates its declared schema.
Message: @{name} doesn’t match its declaration in ascribe.toml: {detail}
Fix: Change the widget’s use to match its declaration in [widgets], or change the declaration.
Read more: Project widgets in the directive reference.