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

Widget shows origin / connection errors

The widget translates server error codes into specific messages:

• origin not in ALLOWED_ORIGINS: add the blog's full origin (scheme included, e.g. https://blog.example.com) to the server's ALLOWED_ORIGINS (comma separated) and redeploy. No trailing slash, no path.
• server configuration incomplete: open /api/health and inspect issues and git.readable.
• cannot reach the server: verify the server URL is reachable; if it is, the origin is likely rejected — check ALLOWED_ORIGINS first.

If an error response lacks CORS headers the browser hides its body and the widget can only show a generic network error, so keep the server up to date.

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.