Diagnostic codes

Every diagnostic code below, by family, with the page or pages that explain it. A code is what a finding prints in brackets, as in warning[<code>], and what [lint] ignore, per-file-ignores and message-ignores take (Linting).

The index covers the reStructuredText and Markdown parser codes, the build.* codes, and the project-analysis codes: std.*, toctree.*, needs.*, intersphinx.*, config and read_error. It does not list yet the fine-grained config.* codes (Configuration diagnostics (config and config.*) lists them), the linkcheck.* codes, or the codes declared in other catalogs, such as the needs.test_report_* and needs.derive_* codes.

General (config, read_error)

Code	Explained on
config	Configuration diagnostics (config and config.*)
read_error	Unreadable source files (read_error)

Source text (source.*)

Code	Explained on
source.tab_in_line	Rendering and transforms, Linting

Block markup (block.*)

Code	Explained on
block.bare_blockquote	Linting
block.blank_line	Linting
block.directive_content_not_permitted	A page can override its browser title, Linting
block.directive_indented_options	Linting
block.directive_malformed	Linting
block.directive_no_argument	A page can override its browser title, Diagnostics, Linting
block.directive_no_content	Linting
block.directive_substitution_only	Linting
block.directive_unknown	Unsupported syntax, Unrendered directives, roles and diagram files, Linting, Coming from Sphinx-Needs
block.enum_number_overflow	Linting
block.footnote_number_overflow	Linting
block.inconsistent_title_level	Linting
block.literal_no_content	Linting
block.paragraph_indentation	Linting
block.substitution_malformed	Linting
block.table_malformed	Linting
block.target_malformed	Linting
block.title_disallowed	Conditional content, Sections, Linting, Multi-line needs
block.title_line	Linting

Inline markup (inline.*)

Code	Explained on
inline.no_closing_marker	Linting
inline.regex_limit_exceeded	Linting
inline.role_malformed	Linting

Directives (directive.*)

Code	Explained on
directive.content_not_permitted	Code blocks, Linting
directive.malformed	Linting
directive.no_argument	Linting
directive.no_content	Todos, Linting
directive.unknown	Linting

Glossaries (glossary.*)

Code	Explained on
glossary	CSS classes, Glossaries, Linting
glossary.definition_as_term	Glossaries, Attributes, Linting

References and targets (std.*)

Code	Explained on
std.any	The :any: role
std.citation_unreferenced	Footnotes and citations
std.confval	Environment variables
std.doc	Cross-referencing with links, How references reach the inventories
std.duplicate_citation	Multi-line needs
std.duplicate_confval	Configuration values, Multi-line needs
std.duplicate_docname	Content inclusion, Needs-domain diagnostics (needs.*), Mounts: extra source trees
std.duplicate_envvar	Environment variables, Multi-line needs
std.duplicate_label	Built-in extension ports
std.duplicate_target	Rendering and transforms, Built-in extension ports, The output, Multi-line needs
std.duplicate_term	Multi-line needs
std.file_outside_roots	Files no root claims (std.file_outside_roots)
std.ref	Footnotes and citations, Cross-referencing with links, How references reach the inventories, Real-time diagnostics
std.term	How references reach the inventories

Toctrees (toctree.*)

Code	Explained on
toctree.circular	Toctree diagnostics
toctree.duplicate_entry	Toctree diagnostics
toctree.empty_glob	Variant-excluded toctree entries (toctree.variant_excluded), Toctree diagnostics, The configuration, 5. Selecting whole files with variant_sources
toctree.missing_root_document	if — gate a whole bundle per variant, Toctree diagnostics
toctree.multiple_toc_parents	Toctree diagnostics
toctree.no_title	toctree navigation, Toctree diagnostics, The configuration
toctree.nonexisting_document	Configuration diagnostics (config and config.*), if — gate a whole bundle per variant, Toctree diagnostics, 5. Selecting whole files with variant_sources
toctree.not_included	toctree navigation, Options, Toctree diagnostics, The configuration, Appendices
toctree.variant_excluded	Files a variant excludes, Variant-excluded toctree entries (toctree.variant_excluded), if — gate a whole bundle per variant, Toctree diagnostics, 5. Selecting whole files with variant_sources

Needs (needs.*)

Code	Explained on
needs.cypher_vocabulary	Needs and filtering, Needs-domain diagnostics (needs.*), Selecting with Cypher, Projections in a needtable
needs.dead_link	Code matching and .* wildcards, Link types, union, Diagnostics gate
needs.duplicate	Rendering and transforms, A need per suite and per case, Diagnostics gate, What the directive renders
needs.dynamic_function	Dynamic functions resolve all eight built-ins, and their filters, When ubCode cannot resolve a call, How rules are computed
needs.extend	The needextend argument: id or filter?
needs.extend_missing_id	needextend renders nothing in a built page, Extending needs, The needextend argument: id or filter?
needs.external	External needs, Test results from sphinx-test-reports
needs.external_link_target_type	Needs-domain diagnostics (needs.*), Link types
needs.import	Imported-needs diagnostics, What you see on the page
needs.import.doctype_ambiguous	Imported-needs diagnostics, What you see on the page
needs.import.filter_empty	Imported-needs diagnostics, What you see on the page
needs.import.ids_unmatched	Imported-needs diagnostics, What you see on the page
needs.invalid_field_value	Field schemas
needs.invalid_link_value	Field schemas
needs.link_condition_failed	Link types, fingerprint
needs.link_condition_invalid	Link types
needs.link_ref	Real-time diagnostics
needs.link_target_type	Needs-domain diagnostics (needs.*), Fields per need type
needs.needextend	Needs-domain diagnostics (needs.*), Fields per need type
needs.schema_config	Diagnostic codes
needs.schema_definition_info	Diagnostic codes
needs.schema_definition_violation	Diagnostic codes
needs.schema_definition_warning	Diagnostic codes
needs.schema_network_info	Diagnostic codes, Diagnostics gate, [workflow]
needs.schema_network_violation	Diagnostic codes, Diagnostics gate
needs.schema_network_warning	Diagnostic codes, Diagnostics gate
needs.src_trace	What the directive renders
needs.undeclared_for_type	Needs-domain diagnostics (needs.*), Fields per need type
needs.variant	Variants, Markup-semantics diagnostics

Intersphinx (intersphinx.*)

Code	Explained on
intersphinx.ambiguous	The :any: role, Loading diagnostics (intersphinx.fetch, intersphinx.inventory), Ambiguous inventory matches (intersphinx.ambiguous)
intersphinx.fetch	Loading diagnostics (intersphinx.fetch, intersphinx.inventory)
intersphinx.inventory	Loading diagnostics (intersphinx.fetch, intersphinx.inventory)
intersphinx.ref	Markdown link cross-references, Cross-referencing with links, Ambiguous inventory matches (intersphinx.ambiguous)

Builds (build.*)

Code	Explained on
build.body_store_write_failed	Build warnings
build.client_asset_missing	Building for production
build.diagram_file_unresolved	Build warnings
build.diagram_unconvertible	Build warnings
build.directive_unhandled	Rendering and transforms, Unsupported syntax, per-file-ignores, What “off” looks like, Coming from Sphinx-Needs
build.download_read_failed	Downloads, Markup-semantics diagnostics
build.empty_site	Build warnings
build.extra_css_read_failed	Options
build.extra_static_collision	Options, [build.html]
build.extra_static_invalid_entry	Options, [build.html]
build.extra_static_read_failed	Options, [build.html]
build.favicon_read_failed	Options, [build.html]
build.footer_icon_invalid	Options, [build.html]
build.highlight_language_unknown	Code blocks, Code blocks are syntax highlighted, The output, How a name is resolved
build.image_no_candidate	Build warnings
build.image_read_failed	Images, Built-in extension ports
build.image_unresolved	Build warnings
build.logo_read_failed	Options, [build.html]
build.manifest_write_failed	Build warnings
build.mermaid_discovered_unusable	Mermaid diagrams
build.mermaid_exec_failed	Mermaid diagrams, [build.mermaid]
build.mermaid_render_failed	Mermaid diagrams, [build.mermaid]
build.mermaid_request_blocked	Mermaid diagrams
build.mermaid_timeout	Mermaid diagrams
build.mermaid_version_unparsed	Mermaid diagrams
build.mermaid_version_unsupported	Mermaid diagrams
build.mount_path_escape	Source-mount confinement (build.mount_path_escape), Mounts: extra source trees
build.need_card_image_invalid	Images on a card
build.need_layout_unknown	Build warnings
build.need_string_link_invalid	Needs and variants, Making the source URLs clickable, Build warnings, The template engine
build.need_style_invalid	Build warnings
build.need_view_failed	A needflow’s :cypher: can also name its EDGES, Build warnings, The output
build.need_view_truncated	Rendering and transforms, Build warnings, Core options
build.needs_json_failed	Build warnings
build.objects_inv_failed	Build warnings
build.pdf_anchor_derived	Warnings and the quality gate
build.pdf_appendix_refused	Options, Appendices
build.pdf_block_unsupported	Index entries, Index entries, Videos, The list of todos, Images, Needs from a list, Needs from a list, Downloads, Downloads, What is not rendered yet
build.pdf_break_unplaceable	Page breaks you write, A table on a landscape page
build.pdf_cover_logo_unreadable	Options, What is not rendered yet
build.pdf_diagram_unrendered	Diagrams, Mermaid diagrams, [build.pdf], What is not rendered yet
build.pdf_directive_unhandled	Unsupported syntax, What is not rendered yet, Coming from Sphinx-Needs
build.pdf_documents_excluded	Toctree diagnostics, What is not rendered yet
build.pdf_font_unreadable	Options, What is not rendered yet
build.pdf_font_unselected	Options, The output
build.pdf_glyph_unavailable	Options, What is not rendered yet
build.pdf_image_unrendered	Warnings and the quality gate
build.pdf_keep_together_oversized	Page breaks you write, A table on a landscape page
build.pdf_landscape_refused	Landscape pages, A table on a landscape page
build.pdf_math_unrendered	Maths
build.pdf_note_oversized	What is not rendered yet
build.pdf_picture_text_too_small	What is not rendered yet
build.pdf_role_unhandled	What is not rendered yet
build.pdf_selection_unreachable	Warnings and the quality gate
build.pdf_table_head_not_repeated	Warnings and the quality gate
build.pdf_table_too_wide	Landscape pages
build.plantuml_exec_failed	External PlantUML renderer, [build.html], [build.pdf], [build.plantuml]
build.plantuml_render_failed	Diagrams, Build warnings
build.plantuml_timeout	External PlantUML renderer, [build.html], [build.pdf], [build.plantuml]
build.plantuml_unexpected_output	External PlantUML renderer
build.plantuml_version_unparsed	External PlantUML renderer, [build.html], [build.pdf], [build.plantuml]
build.plantuml_version_unsupported	External PlantUML renderer, [build.html], [build.pdf], [build.plantuml]
build.redirect_anchor_shadowed	Site output, Options, Build warnings, [build.html]
build.redirect_anchor_unknown	Site output, Options, Build warnings, [build.html]
build.redirect_cycle	Site output, Options, [build.html]
build.redirect_invalid	Site output, Options, [build.html]
build.redirect_source_exists	Site output, Options, [build.html]
build.redirect_target_missing	Site output, Options, [build.html]
build.role_unhandled	Unsupported syntax, Unrendered directives, roles and diagram files, Build warnings
build.search_index_large	A need per suite and per case, Search, Build warnings
build.search_page_conflict	Search
build.source_link_invalid	Options, [build.html]
build.stale_files_kept	Build warnings, The output directory
build.video_glob_unsupported	Images, Built-in extension ports