Configuration 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 reading and validating ssi-config.toml configuration files.
| Message | Exit Code | Hint |
|---|---|---|
| ❌ The 'also' field requires processing = "include" but step [index] (emoji '[emoji]') uses processing = "[processing type]" in [path] | 3 | 💡 The 'also' field is only valid for include steps — remove it or change the step's processing mode to "include" |
| ❌ Ambiguous file resolution in [step emoji] ([path hint], [page scope]) ⚠️ Multiple files found with key '[key]' in the same directory: - [file 1] - [file 2] 💡 Only one file per key per directory is allowed - remove one of these files to resolve the conflict | 3 | 💡 The key is the filename without its extension — files like 'about.html' and 'about.md' share the key 'about' |
| ❌ Both primary and fallback paths missing for emoji [emoji] ⚠️ Primary: [primary path] ⚠️ Fallback: [fallback] 💡 At least one path must exist | 3 | 💡 Check that the source directory or file exists at the configured path relative to ssi-config.toml |
| ❌ Duplicate path [filename] in checksum file [path] | 4 | 💡 Each logical filename must appear at most once — remove or merge duplicate lines |
| ❌ Invalid checksum file format in [path] at line [line] | 4 | 💡 Each line must be: `XXH3_<16hexchars> <filename>` (double space before filename) — fix or remove the bad line in [path] |
| ❌ Invalid checksum format: [checksum] | 4 | 💡 Checksums must be xxHash3-64 values: 16-character hex strings with an XXH3_ prefix (e.g. XXH3_a1b2c3d4e5f60789) |
| ❌ Path security violation in checksum file [path]: [filename] | 4 | 💡 The path [filename] was read from [path] and rejected by path-security policy — remove or correct the offending line |
| Empty configuration - using all defaults | ||
| Config loaded from: [path] | ||
| ❌ Config file path has no parent directory | 3 | 💡 This is a programming error — config file paths are always resolved to absolute paths with a parent directory |
| Configuration file: None (using defaults) | ||
| Config file read failed: [error message] ([path]) | ||
| Parsing config: [path] | ||
| Configuration resolution process starting for [path] | ||
| Complete configuration state logged | ||
| ❌ Field 'context' in [path] contains path separator: [value] | 3 | 💡 Context names cannot contain forward slash or backslash characters |
| ❌ Field 'context' in [path] cannot be empty | 3 | 💡 Use '_' for the default context, or provide a non-empty context name |
| ❌ Deploy directory has no basename: [path] | 4 | 💡 The deploy directory path must end with a directory name, not a trailing separator |
| ❌ Deploy directory has no parent: [path] | 4 | 💡 Use a path with a parent, such as out or build/site — not a filesystem root or other path with no parent segment (SSI needs a resolvable parent directory to place the deploy folder). |
| ❌ Parent directory does not exist for deploy destination '[path]': [parent path] | 4 | 💡 Create the parent directory first — run: mkdir -p [parent path] |
| ❌ Duplicate emoji '[emoji]' is not allowed | 3 | 💡 Each [[step]] must use a unique emoji — choose a different emoji for one of the duplicate steps |
| ❌ Invalid emoji in step[[index]]: '[value]' is a [component type] component (U+[codepoint]) that cannot be used alone | 3 | 💡 Components like ZWJ (U+200D) and variation selectors are only valid within emoji sequences. |
| ❌ Emoji field is empty or whitespace in step [index] | 3 | 💡 Each [[step]] requires a non-empty emoji field — e.g., emoji = "📄" |
| ❌ Invalid emoji in step[[index]]: '[value]' (U+[codepoint]) is in [unicode block] but not a valid emoji | 3 | 💡 Not all characters in emoji Unicode blocks are recognized as emojis. This may require variation selectors or may not be emoji-capable. |
| ❌ Invalid emoji in step[[index]]: '[value]' (U+[codepoint]) needs emoji variation selector U+FE0F | 3 | 💡 This character has both text and emoji presentations. Add U+FE0F after it to select emoji presentation. |
| ❌ Invalid emoji in step[[index]]: '[value]' is not an emoji character | 3 | 💡 Use a standard emoji like 📄, 🔧, or 📦 — text characters and symbols are not valid step emojis |
| ❌ Invalid emoji in step[[index]]: '[value]' contains [count] graphemes (must be exactly 1) | 3 | 💡 Use a single emoji character — compound emojis (like flag sequences) count as multiple graphemes |
| ❌ Invalid emoji in step[[index]]: skin tone modifier '[value]' (U+[codepoint]) cannot be used alone | 3 | 💡 Skin tone modifiers (U+1F3FB-U+1F3FF) must follow a base emoji that supports skin tones. |
| ⚠️ Emoji '[emoji]' (U+[codepoint]) has text-default Unicode presentation — use '[suggested value]' (with VS16 U+FE0F) for reliable emoji rendering | 53 | 💡 Some platforms render these as plain text glyphs — append U+FE0F (VS16) after the emoji in ssi-config.toml to force emoji presentation |
| ❌ Fallback path configured but missing for [step emoji] (primary: '[primary path]', fallback: '[fallback path]') | 3 | 💡 The fallback path doesn't exist on disk — create it or remove the fallback configuration |
| ❌ File Source directory path '[path]' doesn't end with '/' | 3 | 💡 Add a trailing '/' to directory paths in ssi-config.toml to make the intent clear |
| Include Source directory path '[path]' doesn't end with '/' | 💡 Add a trailing '/' to directory paths in ssi-config.toml to make the intent clear | |
| ❌ Destination field '[field]' contains path traversal (../) for emoji [emoji] | 3 | 💡 Destination paths must be relative subdirectories without parent references |
| ❌ Filename contains non-ASCII characters: [path] | 3 | 💡 Only ASCII alphanumeric characters, dots (.), hyphens (-), and underscores (_) are allowed |
| ❌ Cannot extract filename from path: [path] | 3 | 💡 Check that the path is valid and contains a filename component (not just a directory) |
| ❌ Invalid option '[option]' in options (emoji [emoji]) ⚠️ Not valid for [source type] 💡 Valid options: [valid options] | 3 | 💡 Option names are case-sensitive — check for typos in your ssi-config.toml |
| ❌ Invalid processing type in step[[index]] ([emoji] [path]): [processing type] | 3 | 💡 Valid processing types: copy, page, include, preserve, nested |
| ❌ Invalid timezone: '[timezone]' 💡 Must be a valid IANA timezone string (e.g., 'UTC', 'America/New_York', 'Europe/London') | 3 | 💡 Common timezones: UTC, US/Eastern, US/Pacific, Europe/London, Asia/Tokyo |
| ❌ Invalid TOML syntax in [path] at line [line] | 3 | 💡 Check for unclosed quotes, missing brackets, or invalid key-value syntax at the indicated line |
| 📖 Loading configuration from [config path] | ||
| ❌ Missing required field '[field]' in step [index] ([path]) | 3 | 💡 Each [[step]] requires at minimum 'emoji' and 'path' fields — add the field or fix the step index if this is the wrong step |
| Conflicting sort options detected: [value]. Using the first option only | 💡 Remove one of the conflicting sort options from the step configuration | |
| ❌ No parsable size indicator found in filename '[filename]' — treating as zero for human sorting | 3 | 💡 Human sort expects filenames like 'report-5.2G.txt' with size indicators (K/M/G/T) |
| ❌ No [[step]] entries in [config path] | 3 | 💡 Add at least one [[step]] to your ssi-config.toml to define what SSI should process |
| ❌ Path has no filename component: [path] | 4 | 💡 Paths must end with a filename — paths like '.' or those ending with a separator are not allowed |
| ❌ Path traversal (../) not allowed: [path] in [config path] | 3 | 💡 Use paths relative to your source directory without ../ components |
| ❌ Path could not be resolved on disk: [path] in [config path] | 3 | 💡 The path contains .. components but an intermediate directory does not exist — ensure all path components exist, or use a fully resolved path without .. |
| Source Index created and initialized | ||
| ❌ ❌ Unknown config key '[key]' (emoji [emoji]) ⚠️ 'source-options', 'processing-options', and 'type-options' are not valid config keys 💡 Move all options into 'options = [...]' | 3 | 💡 The unified 'options' key accepts all option types — source, processing, and type options all go here |
| ❌ System timezone could not be detected | 3 | 💡 Check that the system timezone is properly configured (e.g., the TZ environment variable or the system timezone database) — or set the 'timezone' option in ssi-config.toml |
| Template basename '[filename]' matches a context name for emoji [step emoji] — this token is ambiguous | 💡 Rename the template file or the section/subdirectory '[filename]' to avoid ambiguity | |
| Both 'template' and 'context' are set (step[[index]], emoji [step emoji]) — 'context' is ignored when 'template' is present | 💡 Template rendering iterates over all contexts; a fixed context override has no effect | |
| ❌ Template name cannot be empty (step [index] in [path]) | 3 | 💡 Provide a non-empty template filename in the 'template' field of the step |
| ❌ The 'template' field requires a TOML file or directory source (step[[index]], emoji [emoji], path '[path]') ⚠️ '[source type]' sources have no iterable contexts 💡 Use 'template' with a .toml file path or a directory path | 3 | 💡 Template rendering needs structured data (TOML sections or directory entries) to iterate over |
| ❌ The 'template' field requires processing = "page" (step[[index]], emoji [emoji], path '[path]') ⚠️ Got processing = "[processing type]" 💡 Add processing = "page" to this step, or remove the 'template' field | 3 | 💡 Templates generate pages from data — they only work with page-type processing |
| ❌ TOML index not set for emoji [emoji] | 3 | 💡 Ensure the TOML source step has a valid path pointing to a .toml file |
| ❌ Nested table value for key '[key]' in [path] ([actual value] values cannot be substituted) | 3 | 💡 TOML data values must be scalar types or arrays — nested tables are not supported |
| ❌ TOML parser encountered syntax error: [details] | 3 | 💡 The parser line above is the source of the problem — fix the syntax there, then compare your file with valid TOML examples at https://toml.io |
| ❌ Copy steps cannot use TOML sources (step[[index]], emoji [emoji], path '[path]') 💡 Use a directory path instead, or use 'processing = "include"' for TOML data sources | 3 | 💡 Copy steps transfer files as-is — use processing = "include" to use TOML data for token substitution |
| ❌ Invalid TOML structure in [path]: found keys at top level: '[keys]' 💡 All keys must be inside sections: • Move to [_] for global keys • Use [page-name] for page-specific keys | 3 | 💡 TOML data files must organize all keys under named sections like [_] or [page-name] |
| ❌ The 'type' field requires processing = "include" (step[[index]], emoji [emoji], path '[path]') ⚠️ Got processing = "[processing type]" 💡 Add processing = "include" to this step, or remove the 'type' field | 3 | 💡 The 'type' field specifies the include source type (e.g., type = "block", type = "toml") |
| ❌ Unexpected security error variant in config path check | 3 | 💡 This is a programming error — config path checks should only produce known security error types |
| unknown content type | ||
| ❌ Unknown field '[field]' in configuration file: [path] | 3 | 💡 Check for typos — run `ssi help config` to see valid configuration fields |
| unknown source provider | ||
| Unrecognized source option '[option]' for [source type] source. Recognized options: [recognized values] | 💡 Check for typos in the option name — options are case-sensitive | |
| ❌ Content type '[content type]' not supported by [source type] (emoji [emoji]) | 3 | 💡 Different source types support different content types — check the documentation for your source type |
| ❌ Unrecognized processing mode '[processing type]' for emoji [emoji] | 3 | 💡 Valid file-processing modes: copy, page, preserve, copylist, nested |
| Primary source not found, using fallback for emoji [step emoji] | 💡 Primary: [primary path] → Fallback: [fallback path] | |
| ❌ The 'major' field is missing from version.toml — version.toml must contain major, minor, and patchlevel fields (programming error) | 1 | |
| ❌ The 'major' field in version.toml is not a valid integer — version.toml must contain only integer values (programming error) | 1 | |
| ❌ The 'minor' field is missing from version.toml — version.toml must contain major, minor, and patchlevel fields (programming error) | 1 | |
| ❌ The 'minor' field in version.toml is not a valid integer — version.toml must contain only integer values (programming error) | 1 | |
| ❌ The 'patchlevel' field is missing from version.toml — version.toml must contain major, minor, and patchlevel fields (programming error) | 1 | |
| ❌ The 'patchlevel' field in version.toml is not a valid integer — version.toml must contain only integer values (programming error) | 1 | |
| ❌ version.toml could not be parsed as valid TOML — [details] (programming error) | 1 |