Troubleshooting

Troubleshooting

Quick Diagnostics

1. Run ssi validate — catches most configuration problems
2. Run ssi --verbose deploy — shows token processing and file search paths
3. Check error messages — they include file paths, causes, and suggestions

Common Issues

Tokens not replaced

Tokens like 📝title appear unchanged in output.

• Missing [[step]] in config for that emoji
• Wrong emoji — config and template must match exactly
• Content file missing — check path in config
• Per-page directory missing — check content/pages/{page}/ exists

Use --trace-tokens with --single-file to see exactly how each token resolved:

ssi deploy --single-file pages/about.html site/ - --trace-tokens
                

No output generated

Command completes but no files appear.

• Verify [[step]] section exists in ssi-config.toml
• Check source directory has files to process
• Check the deploy directory argument

File not found

• Run SSI from the project root (where ssi-config.toml is)
• Use relative paths in config (content/ not /absolute/content/)
• Verify path separators are forward slashes

Config syntax errors

Common mistakes:

# Emoji must be quoted
                emoji = "📝"           # correct
                emoji = 📝             # wrong
                
                # Both emoji and path are required
                [[step]]
                emoji = "📝"
                path = "content/"
                
                # Each step needs a unique emoji
                

Markdown appears as plain text

Add type = "markdown" to the include step config.

HTML tags appear escaped (<div>)

Use type = "html" (not type = "plain") for HTML fragment includes.

External path rejected

# Add allow-external-paths option to the step
                [[step]]
                emoji = "📚"
                path = "../shared/"
                processing = "include"
                options = ["allow-external-paths"]
                

Also requires ssi --allow-external-paths deploy ... on the command line.

Missing build-time files (CI/CD)

Use fallback = to provide local defaults for files generated by CI:

[[step]]
                emoji = "🔧"
                path = "build-info.toml"
                fallback = "build-info-defaults.toml"
                processing = "include"
                options = ["inline"]
                

Getting More Help

ssi --verbose deploy site/ output/   # shows processing detail
                ssi validate site/                   # checks configuration
                ssi help exit-codes                  # exit code reference
                

For per-error-code help: ssi help errors <name>