Skip to content

Troubleshooting

Non-UTF8 SKILL.md parse failures

Symptom:

  • Warnings mentioning invalid UTF-8 or parse errors for SKILL.md.

Fix:

file -I path/to/SKILL.md
iconv -f ISO-8859-1 -t UTF-8 path/to/SKILL.md > /tmp/SKILL.md && mv /tmp/SKILL.md path/to/SKILL.md

Then re-run:

razin scan -r . -o output/

Read-only output path errors

Symptom:

  • Output directory is not writable before scan starts.

Fix:

mkdir -p output
chmod u+w output
razin scan -r . -o output/

Custom rule YAML errors

Symptom:

  • Invalid YAML, invalid schema, or invalid rule operation errors when using custom rules.

Fix:

razin validate-config -r . -R ./enterprise-rules
razin scan -r . -R ./enterprise-rules --rules-mode replace

Validate one file directly:

razin validate-config -r . -f ./enterprise-rules/custom_rule.yaml

Duplicate rule IDs in overlay mode

Symptom:

  • Overlay scans fail with duplicate rule_id conflicts.

Fix options:

# Fail fast and keep IDs unique
razin scan -r . -R ./enterprise-rules --rules-mode overlay --duplicate-policy error

# Allow custom rule to replace bundled rule
razin scan -r . -R ./enterprise-rules --rules-mode overlay --duplicate-policy override

Homebrew installs old version

Symptom:

  • razin --version from brew is behind latest release.

Fix:

brew update
brew upgrade razin
brew info razin

If you installed from tap, make sure the tap is correct:

brew tap | grep -E 'theinfosecguy/(homebrew-tap|tap)'

Docs build failures

Symptom:

  • CI fails on docs checks.

Fix:

uv run mkdocs build --strict
uv run mdformat README.md docs