Troubleshooting

Running into problems? Here are solutions to the most common issues people encounter with JamComments.

Comments Not Appearing

The comment form shows, but no existing comments display

Check your environment:

• In development mode, dummy comments are shown instead of real ones
• Make sure NODE_ENV or JAM_COMMENTS_ENVIRONMENT is set to "production"

Check your path:

• Comments are tied to specific paths (like /posts/my-article)
• If your path has a trailing slash in one place but not another, comments won’t match
• Be consistent: always use /posts/my-article or always use /posts/my-article/

Check your domain:

• The domain in your integration must exactly match your JamComments site domain
• www.yoursite.com and yoursite.com are different domains
• Check for typos or extra subdomains

Comments exist in the dashboard but not on the site

Check comment status:

• Only approved comments appear on your site
• Comments in “pending” status are visible only in the dashboard
• Check your site settings for auto-approval settings

Check your build:

• Static site generators need to rebuild to show new comments
• If you don’t have webhooks set up, you need to trigger a manual build
• New comments appear after the next deployment

Can’t Submit Comments

”Invalid domain” error

• Your site’s domain in the integration doesn’t match the domain in your JamComments account
• Go to Site Settings and verify the exact domain
• Include subdomains if you use them (e.g., blog.yoursite.com)

“Invalid API key” error

• Your API key might be wrong or expired
• Generate a new key in your account settings
• Make sure the key is complete (don’t truncate it)

“Something went wrong” error

• Check your browser’s developer console for more details
• Common causes: network issues, ad blockers, or CSP (Content Security Policy) blocking requests

Webhooks Not Firing

No builds triggered after new comments

Check webhook URL:

• Go to your site settings and verify the webhook URL is correct
• Try copying the URL and visiting it directly — it should trigger a build

Check in development mode:

• Webhooks only fire in production
• Development mode submissions are “silent” and don’t trigger webhooks

Test with a manual trigger:

• Toggle the “Remove Branding” setting on/off
• This should trigger all webhooks immediately
• If it doesn’t, your webhook URL might be wrong

Webhook worked before but stopped

• Check if your hosting provider’s hook URL changed
• Vercel, Netlify, and others sometimes rotate deploy hook URLs
• Update the webhook URL in JamComments if it changed

Styling Issues

Comment form looks wrong or broken

Check for CSS conflicts:

• JamComments uses the jc-* prefix on all CSS classes
• Check if your site’s CSS is accidentally targeting these classes
• Use your browser’s dev tools to inspect the comment form

Check for missing styles:

• The comment form includes its own CSS
• If styles aren’t loading, check your browser’s Network tab
• Ad blockers or CSP policies might block the stylesheet

Dark mode not working

• JamComments respects your site’s CSS custom properties
• See the styling documentation for how to configure dark mode
• You may need to set CSS variables for dark mode colors

Email Notifications

Not receiving comment notifications

Check spam folders:

• JamComments emails sometimes end up in spam
• Add [email protected] to your contacts

Check your site settings:

• Make sure notifications are enabled for your site
• Check if you accidentally muted the site

Commenters not getting reply notifications

• Only JamComments account holders receive reply notifications
• Anonymous commenters won’t get emails
• The email address they provide is only used for Gravatar, not notifications

Build and Performance Issues

Slow build times

Use batch mode:

• Some integrations support batch fetching (Astro, for example)
• This fetches all comment data upfront instead of per-page
• See your integration’s documentation for batch mode setup

Check comment volume:

• Sites with hundreds of comments per page will build slower
• Consider paginating old comments

Layout shift when comments load

Reserve space:

• The comment form loads asynchronously
• Reserve vertical space in your layout to prevent layout shifts
• Add a min-height to your comments container

Use a skeleton loader:

• Add a placeholder that matches the comment form’s size
• Replace it when the form loads

API Issues

REST API returning empty data

Check your authorization header:

• Must be exactly: Authorization: Bearer YOUR_TOKEN
• Common mistake: forgetting “Bearer” or using wrong case

Check your domain parameter:

• Must exactly match your JamComments site domain
• No protocol (no https://)
• No trailing slash

Rate limiting errors

• The AI moderation prompt testing is rate-limited to 5 requests per minute
• General API usage doesn’t have strict rate limits, but excessive usage may be throttled
• If you hit limits, wait a few minutes and try again

Still Having Issues?

If you’re stuck:

1. Check the FAQ — Common questions answered
2. Review your integration docs — Each framework has specific troubleshooting tips
3. Contact support — Include:
   • Your site domain
   • The integration you’re using
   • The exact error message
   • Steps you’ve already tried