#Troubleshooting

#Health is degraded

The issues array lists missing or invalid fields. Common causes:

• COMMENTS_SECRET shorter than 32 bytes
• Empty ALLOWED_ORIGINS
• MODERATION_REQUIRED is not exactly true or false
• Moderation on but no complete mail provider

#Comments do not load

1. Check git.readable
2. Check COMMENTS_REPO spelling and case
3. Check the PAT includes that repository
4. Private repositories work as long as the PAT has Contents: Read

#Approved comment is not visible

Reads are cached for up to 60 seconds. If it still does not appear:

1. Confirm comments/<slug>.json changed in the repository
2. Confirm the widget post matches the normalized slug
3. Clear browser cache

#Approve returns 403

• origin_not_allowed: the submitting origin was removed from ALLOWED_ORIGINS
• GitHub 403: PAT scope or repository mismatch, or the token was revoked

#Approve returns 409

A comment with the same id exists with different content. Existing comments are never overwritten; edit the file manually if you really need to replace it.

#Submit returns 429

More than 5 submissions from the same IP within 10 minutes. Wait for the window to pass.

#Turnstile always fails (when enabled)

• Site key and secret must come from the same Turnstile widget
• Verify the blog domain is listed on that widget
• Tokens are single-use; refresh before retrying
• If neither key is set, the captcha is intentionally off
• The blog domain must be listed on that widget
• Tokens are single-use; refresh before retrying

#No review email

1. Verify the sending domain in Resend or MailPort
2. Check the provider logs
3. Check spam
4. For MailPort, confirm the moderator domain is allowlisted

#Review link expired

Links last 7 days. Ask the commenter to submit again.

#Same-repo mode redeploys constantly

Configure the platform's skip-build rule to exclude comments/, as described in Storage location.

#Old links break after rotating the secret

Expected. Rotating COMMENTS_SECRET invalidates every unused review link.