> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Common errors & solutions

> A guide to common issues when working with ButterCMS and how to resolve them quickly.

## 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:**

```javascript theme={null}
// 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}`
  }
});
```

2. **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)
3. **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

{/* IMAGE_SOURCE: file_path="blog-posts/gsd/quarkus-tutorial-event-app.md" */}

![Read and Write API Token location in ButterCMS settings](https://cdn.buttercms.com/Ruyum7H1RVmKOkW4wxZt)

### 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](mailto: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](https://cdn.buttercms.com/vhvpuXD8T5O9ipVjpTJ9)

#### 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:**

| Cause                   | Solution                                                    |
| ----------------------- | ----------------------------------------------------------- |
| Content not published   | Check if content status is "published" in the dashboard     |
| Wrong locale parameter  | Verify the `locale` parameter matches your content's locale |
| Cache not cleared       | Wait a few minutes or trigger a cache refresh               |
| Incorrect page type key | Double-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

```javascript theme={null}
// 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:

<CardGroup cols={2}>
  <Card title="Contact Support" icon="headset" href="../contact-status/contact-support">
    Reach out to our support team via chat or email
  </Card>

  <Card title="API Error Codes" icon="code" href="./api-error-codes">
    Full reference of all API error codes
  </Card>
</CardGroup>