Skip to main content

​
Authentication & API issues

​
Missing or invalid API token

Symptom: API requests return 401 Unauthorized with the message “Authentication credentials were not provided” or “Invalid token.” Common Causes:
  • The API token is not included in the request
  • Using an incorrect API token (Read vs Write)
  • Typo in the API token value
Solutions:
  1. Verify your token is included correctly:
// Correct: Using query parameter
const url = `https://api.buttercms.com/v2/posts?auth_token=${YOUR_READ_TOKEN}`;

// Correct: Using Authorization header
fetch('https://api.buttercms.com/v2/posts', {
  headers: {
    'Authorization': `Token ${YOUR_READ_TOKEN}`
  }
});
  1. Check you’re using the right token:
    • Read API Token - For fetching content (pages, posts, collections)
    • Write API Token - For creating/updating content (requires request to support)
  2. Find your API tokens:
    • Navigate to your ButterCMS dashboard
    • Click your profile avatar in the sidebar
    • Select Settings
    • Copy the Read API Token from the API Tokens section
Read and Write API Token location in ButterCMS settings

​
Write API token not working

Symptom: You’re trying to create or update content but receive 401 Unauthorized. Solution: The Read API token cannot be used for write operations. You need a separate Write API Token. Contact support@buttercms.com to request write access for your account.

​
Content display issues

​
WYSIWYG formatting problems

When content is copied from another document and pasted into ButterCMS, formatting conflicts may arise due to:
  1. Formatting from the original document transfers differently than intended
  2. Your site’s CSS overrides WYSIWYG editor formatting (most common)

​
Issue: formatting changes affect text before or after highlighted section

Cause: Missing proper line breaks in your content. Solution: Ensure you have proper line breaks between paragraphs. Use Shift+Enter for soft breaks if needed. How to fix line break issues in WYSIWYG editor

​
Issue: line-height of bullet points looks different on site

Cause: Your website’s CSS controls the final appearance. Solution: Configure the line-height in your website’s CSS. The WYSIWYG editor preview may differ slightly from your final rendered content.

​
Issue: can’t add spacing between paragraphs

Cause: Your application’s CSS may override <p> tags to have zero margin. Solutions:
  • Use <br> tags for line breaks
  • Press Shift+Enter instead of Enter for soft breaks
  • Adjust your CSS to allow paragraph margins

​
API response issues

​
Content not appearing

Symptom: API call succeeds but content doesn’t show or returns empty. Common Causes & Solutions:
CauseSolution
Content not publishedCheck if content status is “published” in the dashboard
Wrong locale parameterVerify the locale parameter matches your content’s locale
Cache not clearedWait a few minutes or trigger a cache refresh
Incorrect page type keyDouble-check the page type key in your API call

​
Wrong locale content returned

Symptom: API returns content in the wrong language or “Invalid locale parameter” error. Solutions:
  1. Verify locale exists: Go to Settings > Localization and confirm the locale is configured
  2. Use correct locale slug: The API uses the locale slug (e.g., en, es, fr), not the display name
  3. Check content exists in that locale: Not all content may be translated
// Correct locale usage
const response = await butter.page.retrieve('landing_page', 'homepage', {
  locale: 'es' // Use locale slug, not "Spanish"
});

​
Image & media issues

​
Images not loading

Symptom: CDN images return 404 or don’t display. Solutions:
  1. Check the URL format: Ensure the URL is complete and starts with https://cdn.buttercms.com/
  2. Verify the file exists: Go to Media Library and confirm the file is uploaded
  3. Check file permissions: Some files may have been deleted or replaced

​
Slow image loading

Solutions:
  • Optimize file sizes: Keep images under 500KB for web use
  • Use appropriate dimensions: Don’t upload 4000px images for thumbnails
  • Enable automatic compression: ButterCMS automatically compresses and converts images to WebP
  • Use Image API transformations: Add parameters to resize on-the-fly
// Resize image to 800px width
https://cdn.buttercms.com/YOUR_IMAGE_ID?w=800

// Resize and convert to WebP
https://cdn.buttercms.com/YOUR_IMAGE_ID?w=800&output=webp

​
Preview issues

​
Preview not showing latest changes

Symptom: Preview shows old content despite making changes. Solutions:
  1. Save your changes: Click “Save Draft” before previewing
  2. Hard refresh the preview: Use Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
  3. Check preview URL configuration: Verify your preview URL is correctly set in Settings

​
Preview URL not working

Symptom: Clicking preview opens a broken page or wrong URL. Solutions:
  1. Verify preview URL format: Go to Content Types > [Your Page Type] > Settings
  2. Include required parameters: Your preview URL should include {slug} placeholder
  3. Check your frontend handles previews: Your app needs to support draft content fetching

​
Webhook issues

​
Webhooks not triggering

Symptom: Content changes don’t trigger webhook calls. Solutions:
  1. Verify webhook URL is accessible: Test with a service like webhook.site
  2. Check webhook is enabled: Go to Settings > Webhooks and confirm status
  3. Verify event types: Ensure the correct events are selected (publish, update, delete)
  4. Check for HTTPS: Webhook URLs must use HTTPS

​
Webhook receiving old data

Symptom: Webhook payload contains stale content. Solution: Webhooks are triggered asynchronously. If you need the latest content, make an API call to fetch fresh data rather than relying solely on the webhook payload.

​
Still Need Help?

If you can’t find a solution to your issue:

Contact Support

Reach out to our support team via chat or email

API Error Codes

Full reference of all API error codes