File Operations 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 file reading, writing, and copy operations during site deployment.
| Message | Exit Code | Hint |
|---|---|---|
| ❌ Cannot extract filename from external path: [path] | 4 | 💡 External paths must point to a file, not a directory or bare path |
| ❌ Failed to resolve canonical path for [path]: [I/O error message] | 4 | 💡 Check that the file exists and all directories in the path are accessible |
| ❌ Deployed file checksum mismatch: [path] 💡 The deployed file no longer matches the recorded checksum (copy may have failed, or the file changed after deploy) | 4 | 💡 Re-deploy to fix this, or regenerate the checksum file if the file was intentionally changed |
| ❌ Source file checksum mismatch: [path] 💡 The file has been modified since the checksum was generated. Update the checksum file or restore the original file | 4 | 💡 Run `xxh3sum <file>` to generate an updated checksum |
| ❌ File [path] is missing from checksum file [checksum file] 💡 Either add the file to the checksum file, or remove the 'checksum' option | 4 | 💡 Run `xxh3sum <file>` and add the output line to the checksum file |
| ⚡ Skipped (checksum match): [path] | ||
| ❌ Configuration file not found: [filename] | 4 | 💡 Check the file path and name for typos |
| ❌ Directory [path] does not contain an ssi-config.toml file | 4 | 💡 Is [path] an SSI site source directory? Did you use a non-default config file name? (Try --config) |
| ❌ Data file not found: [path]/[page] | 5 | 💡 Check that the data file exists for this page context |
| ✔️ Would create symlink: [link] -> [target] | ||
| ✔️ Would process site from [source] to [destination] | ||
| Dry run: Would update symlink [link] -> [target] | ||
| [DRY RUN] Would write file: [path] | ||
| ✔️ Extracted base name: [filename] | ||
| ❌ Failed to [operation] [path]: does not exist | 4 | 💡 Check the file path for typos and verify the file has not been moved or deleted |
| ❌ Error reading file [path]: [I/O error message] | 4 | 💡 Check that the file exists, is readable, and is not locked by another process |
| ❌ File [path] contains invalid UTF-8 encoding | 4 | 💡 SSI only processes UTF-8 text files — convert the file encoding or use a copy step for binary files |
| ❌ Invalid path configuration: [path] | 3 | 💡 The fix depends on the source type. For a git include source, the path must be relative to the site and end with `.git`. For template, index, or other file-backed sources, the path must point to a normal file with a name under the source tree — not a bare directory — and be relative to the source directory. Check the path value in ssi-config.toml against this message and the on-disk layout. |
| ❌ Invalid path structure: [path] | 4 | 💡 The path is missing a parent directory, filename, or other part SSI needs — check the path in ssi-config.toml or CLI arguments |
| ❌ Failed to [operation] [path]: [I/O error message] | 4 | 💡 Check file permissions, disk space, and that the path is accessible |
| ❌ Key [key] not found in [source type] source | 5 | 💡 Check that the key name matches a file or data entry in the source — key names are case-sensitive |
| 🫙 No file sources to process in [config path] 💡 If you expected a file build, add file-processing `[[step]]` entries to that file. If the site is TOML-only or metadata-only, no file steps may be intentional. | ||
| ❌ Path does not exist: [path] | 4 | 💡 Verify the path in ssi-config.toml — paths are relative to the source directory |
| ❌ Failed to [operation] [path]: permission denied | 4 | 💡 Check file and directory permissions — you may need read access to source files and write access to the deploy directory |
| ❌ Path [path] exists but is not a symbolic link | 4 | 💡 read_link applies only to symlink paths — use a regular file path only where a symlink was intended |
| ❌ Source not found: [path] | 4 | 💡 [path hint] |
| ❌ Cannot process special file type: [path]. Super-Simple Includes only supports regular files, not [file type] | 4 | 💡 Remove this file from your source directory, or exclude it from the step |
| ❌ non-regular file | 4 | 💡 SSI can only process regular files and symlinks — devices, pipes, and sockets are not supported |
| ❌ Failed to create symlink at [path]: 💬io_kind | 4 | 💡 Check that the parent directory exists and you have write permission |
| ❌ Symlink destination has no parent directory: [path] | 4 | 💡 The destination path must be within an existing directory |
| ❌ Target file already exists: [path] | 4 | 💡 Another step may have already written this file — check for overlapping output paths in ssi-config.toml |
| Validating checksums for [step emoji] [path]... |