Validation Messages
See Errors & Warnings Catalog for the full index, and Errors & Warnings Guide for a narrative explanation of message categories, exit codes, and common fixes.
Messages from the ssi validate command, which checks site output for broken links, HTML structure, and accessibility issues.
| Message | Exit Code | Hint |
|---|---|---|
| ⚠️ The 'also' emoji '[emoji]' in step [index] shadows a primary emoji in [path] | 53 | 💡 The 'also' emoji is already the primary emoji of another step — first-match-wins in config order applies, which may be surprising |
| ❌ Cannot read git commit hash from [path] (💬io_kind) 💡 Check repository integrity or use --suffix-timestamp | 50 | 💡 The git hash is used for atomic deployment suffixes — if git is unavailable, use an alternative suffix mode |
| ⚠️ Source file '[source]' (step [step]) contains token '[token]' from earlier step (emoji [emoji]) — this token **will not be replaced**. Consider reordering steps or using a different emoji. | 53 | 💡 Include tokens are only replaced within the page step they follow — earlier-step tokens are invisible to later steps |
| unclosed block | ||
| bare '@' not followed by identifier | ||
| unexpected closing brace | ||
| unterminated string | ||
| ⚠️ CSS parse error in '[path]' (line [line], column [column]): [excerpt] | 53 | 💡 Check for unclosed braces, missing semicolons, or invalid property syntax at the indicated location |
| ⚠️ Could not read some CSS source files for structure checks — not valid UTF-8: 🧮quantity_count_encoding; permission or access denied: 🧮quantity_count_permission; other: 🧮quantity_count_other | 53 | 💡 Those files were omitted from the CSS structure scan — fix encoding, permissions, or paths, or expect incomplete coverage |
| Deploy directory set: [path] | ||
| ❌ Git repository at [path] has no commits 💡 Make an initial commit or use --suffix-timestamp instead | 50 | 💡 A git hash suffix requires at least one commit in the repository |
| ⚠️ aria-hidden on interactive element in '[path]': aria-hidden="true" on a focusable element removes it from the accessibility tree while keeping it keyboard-reachable — use display:none or remove the element instead. | 53 | 💡 Users can still Tab to this element but screen readers won't announce it — this creates a confusing experience |
| ⚠️ ARIA reference to missing id in '[path]': [attribute]="[id]" references an id that does not exist in this page. | 53 | 💡 Add an element with id="[id]" to the page, or fix the ARIA reference to use an existing id |
| ⚠️ Div-soup detected in '[path]': [count] <div> elements with no semantic sectioning elements. Use <main>, <nav>, <article>, <section>, <header>, <footer>, or <aside> instead. | 53 | 💡 Semantic HTML elements improve accessibility and SEO — replace layout <div> elements with appropriate HTML5 tags |
| ⚠️ Duplicate id attribute in '[path]': id='[id]' appears more than once. Each id must be unique within a page. | 53 | 💡 Use class attributes for shared styling — id must be unique per page for links and JavaScript to work correctly |
| ⚠️ Embedded <style> tag in '[path]': move styles to an external stylesheet linked with <link rel="stylesheet"> instead. | 53 | 💡 External stylesheets are cached by browsers and can be shared across pages |
| ⚠️ Heading hierarchy skip in '[path]': [tag] follows [other tag] (levels must not skip) | 53 | 💡 Headings should follow a logical sequence (h1 → h2 → h3) without skipping levels |
| ⚠️ Inline style attribute in '[path]': found style="..." on <[tag]>. Move styles to an external stylesheet linked with <link rel="stylesheet">. | 53 | 💡 External stylesheets are cached by browsers and keep content separate from presentation |
| ⚠️ Invalid ARIA role in '[path]': role="[name]" is not a valid ARIA role. See https://www.w3.org/TR/wai-aria/#role_definitions for valid values. | 53 | 💡 Common valid roles: banner, navigation, main, complementary, contentinfo, search, form, region |
| ⚠️ Missing alt attribute on <img> in '[path]': add alt="" for decorative images or descriptive alt text for meaningful images. | 53 | 💡 Screen readers use alt text to describe images — use alt="" (empty) only for purely decorative images |
| ⚠️ No <h1> element in '[path]': pages with heading elements should have exactly one <h1> as the page title. | 53 | 💡 Add an <h1> element as the main page title for accessibility and SEO |
| ⚠️ Missing lang attribute on <html> in '[path]': add lang="en" (or the appropriate language code) so screen readers pronounce content correctly. | 53 | 💡 Add lang="en" to your <html> tag (or the appropriate BCP 47 language code for your content) |
| ⚠️ Multiple <h1> elements in '[path]': pages should have exactly one <h1> | 53 | 💡 Use <h2> or lower for section headings — the <h1> should be the single page title |
| ⚠️ Non-conforming HTML element in '[path]': <[tag]> is not valid HTML5 — use CSS or a modern semantic equivalent. | 53 | 💡 Deprecated elements like <center>, <font>, and <marquee> should be replaced with CSS styling |
| ⚠️ HTML parse error in '[path]': [excerpt] | 53 | 💡 Check for malformed tags, unclosed elements, or invalid attribute syntax |
| ⚠️ Unlabeled form input in '[path]': <input> element has no associated label, aria-label, or title attribute. | 53 | 💡 Use <label for="id"> or aria-label="description" so assistive technology can identify the input |
| ❌ Invalid TOML in include source file [path]: [error message] | 52 | 💡 Fix the TOML syntax in that file — unclosed tables or string quotes are common causes |
| ⚠️ (not configured) | 53 | 💡 Used when expanding include step path validation to show the fallback column |
| ⚠️ Include step [emoji] has no accessible path (primary '[primary path]'; fallback [fallback path]). Pages still reference: [tokens] | 53 | 💡 The configured include directory or file does not exist — fix the path, add a valid fallback, or remove tokens that use this step |
| ❌ Invalid git HEAD format in [path] 💡 Check repository integrity or use --suffix-timestamp | 50 | 💡 The .git/HEAD file should contain a ref pointer or a commit hash — try `git status` to check |
| ❌ Leftover token '[token]' in [template] — emoji [emoji] is not configured anywhere (possible typo) | 50 | 💡 Check that the emoji matches a [[step]] in ssi-config.toml — this emoji is not used by any step |
| ❌ Leftover token '[token]' in [template] - key not found in [emoji] source | 50 | 💡 The emoji is configured but the key doesn't match any file or data entry — check for typos in the token name |
| ❌ Leftover token '[token]' in [template] — emoji [emoji] is configured for a non-include step, not includes | 50 | 💡 Non-include-step emojis cannot be used as include tokens — use an emoji from an include step instead |
| ⚠️ Case mismatch in '[path]': '[URL]' does not match filesystem (found as '[expected value]') | 53 | 💡 Many web servers are case-sensitive — update the link to match the exact filename case |
| ⚠️ file: URL in '[path]': '[URL]' — file: URLs are local paths and will not work in a web browser | 53 | 💡 Replace the file: URL with a relative path or a proper https: URL; file: URLs are local-only and should not appear in deployed HTML |
| ⚠️ Missing anchor in '[path]': '[URL]' references anchor '[anchor]' which does not exist in the target | 53 | 💡 Add an element with id="[anchor]" to the target page, or fix the link's #anchor |
| ❌ Broken link in '[path]': target '[URL]' does not exist | 52 | 💡 Check the href for typos — the linked file must exist in the deployed output |
| ❌ Template output path '[path]' cannot be normalized to a site-relative path (too many '..' segments escape above the site root) | 52 | 💡 This path should be produced by the pipeline; check step paths and output configuration for invalid relative segments |
| ❌ Loose ref file at 💬paths_ref_path contains an invalid hash — possibly corrupt or tampered git state 💡 Check repository integrity or use --suffix-timestamp | 50 | 💡 The loose ref file should contain a 40- or 64-character hex git object hash — try `git fsck` to check repository health |
| ⚠️ Missing include sources (referenced but files don't exist): [tokens] | 53 | 💡 Your pages reference these tokens but the corresponding source files are missing — create them or remove the tokens |
| ❌ Not in a git repository (searched from [path]): 💬io_kind 💡 Use --suffix-timestamp or --suffix-length instead of git hash | 50 | 💡 Git hash suffixes require the source directory to be inside a git repository |
| ⚠️ Orphaned include files (generated but not referenced): [file list] | 53 | 💡 These files are in your include source but no page uses their tokens — remove them or add the tokens to a page |
| ⚠️ Include step [emoji] ('[path]') appears before all page steps and is invisible to every page — its tokens will **never** be substituted. Move this step after at least one page step. | 53 | 💡 The step order in ssi-config.toml matters — page steps must come before include steps that should apply to them |
| ⚠️ Output path '[path]' is written by step [emoji] and also by step [other emoji] — later step wins | 53 | 💡 Use different destination paths or remove one of the conflicting steps |
| ❌ Found subdirectories in [type] source '[source]' | 50 | 💡 This source type does not process subdirectories — move files to the top level or use a different source type |
| ❌ Could not read page source '[source]' at [path] to check for subdirectories: [error message] | 50 | 💡 The subdirectory pre-check was skipped; fix permissions or the path, or expect a clearer error when the pipeline reads this directory |
| ⚠️ Token key '[key]' contains invalid character U+[error code] — token key bodies may only contain alphanumeric characters, underscores, and hyphens | 53 | 💡 Rename the source file to use only ASCII letters, digits, underscores, and hyphens |
| ⚠️ Token key is empty — empty keys produce invalid automaton behavior and are rejected | 53 | 💡 Ensure all source files and TOML keys have non-empty names |
| ⚠️ Token key '[key]' ends with U+[error code] — token keys should end with alphanumeric characters | 53 | 💡 Rename the source file to end with an alphanumeric character (letter or digit) |
| ⚠️ Token key '[key]' starts with U+[error code] — token keys should start with alphanumeric characters | 53 | 💡 Rename the source file to start with an alphanumeric character (letter or digit) |
| Skipping '[path]' during unicode scan: I/O error ([I/O error message]) — a binary file would not be reported this way | ||
| ⚠️ Hidden files in source directory not referenced in any [[step]]: [file list] Consider adding these to .gitignore, or add them to a [[step]] in ssi-config.toml. | 53 | 💡 Hidden files (starting with '.') are often editor or system files that don't belong in the site output |
| ⚠️ Unreferenced files in source directory: [file list] These files exist in your source directory but are not used. Remove them or add them to a [[step]] in ssi-config.toml. | 53 | 💡 Every file in the source directory should belong to a [[step]] — unused files may indicate a misconfiguration |
| Checking for unused keys in include sources | ||
| ⚠️ Unused key '[value]' in source [emoji] | 53 | 💡 This key exists in the source but no page uses it — remove the file/entry or add a token referencing it |
| Checking CSS structure... | ||
| ❌ | 50 | 💡 Fix the errors listed above in your ssi-config.toml, then run validation again |
| ❌ | 50 | 💡 Fix the errors listed above, then run `ssi validate` again |
| Checking HTML structure... | ||
| ❌ Include validation error: [error message] | 50 | 💡 If the text mentions TOML, fix the syntax in that file (unclosed tables or string quotes are common). For path or permission errors, confirm the file exists and is readable. For step or emoji issues, check [[step]] blocks and token names in ssi-config.toml. |
| Checking include source usage for '[source]'... | ||
| Include validation: [count] referenced token entries | ||
| Checking internal links... | ||
| 🎖️ Configuration validation of '[path]' passed | ||
| 🏅 Content validation of '[path]' passed | ||
| 🎨 CSS structure validation passed | ||
| 🏛️ HTML structure validation passed | ||
| 🥈 Include validation passed | ||
| 🔗 Link validation passed | ||
| 🥉 Source validation of '[path]' passed | ||
| 🔐 Source file checks passed | ||
| Validation processing complete in [elapsed time] seconds | ||
| Running quick validation for [config path] (config only) | ||
| Checking source files... | ||
| Running source validation for [source] | ||
| Content validation collected [count] templates | ||
| Unreferenced source file check: [count] unreferenced file warnings | ||
| Unused key detection: [count] matched key entries | ||
| ❌ File '[path]' has extension '[actual value]' which does not match the declared content type '[content type]' | 6 | 💡 Check the file extension or change the content type in your ssi-config.toml |