Troubleshooting

unsupported language

Symptom: A file is ignored by the scanner or the public parser returns an unsupported-language error.

Check: Confirm the filename ends in .go, .js, .jsx, .ts, .tsx, or .py. Detection is based on the final extension and is case-insensitive.

Remediation: Rename or convert the input, or use the Go API's WithLanguage option when the file extension is not representative. The CLI does not expose forced-language selection.

No Markdown appears

Symptom: The command succeeds but the output directory has no useful index.md.

Check: Run with --no-cache and inspect the command result. Confirm that the root contains supported files and that .gitignore, a built-in directory skip, or --exclude did not remove them.

Remediation: Run sunset clean <path> and then sunset parse --no-cache <path>. A successful project with at least one parsed file creates index.md and a files/ directory.

Update skips a file that should be re-parsed

Symptom: update reports a file as skipped after an unexpected result.

Check: Inspect .sunset/cache/cache.json and compare the source file with the last run. The cache key is the relative path and the value is a SHA-256 content hash.

Remediation: Run sunset parse --no-cache <path> to bypass the cache. If the generated state still looks wrong, clean .sunset and repeat the parse.

The process exits non-zero

Sunset returns non-zero for an invalid root, an engine-level failure, or when one or more files produced errors. Re-run without --quiet to see the result summary and per-file errors. With --quiet, normal output is suppressed and the current CLI also suppresses the result block that contains per-file error details.