Common Errors & Solutions

Quick reference for troubleshooting the most common errors you might encounter when using BlokMCP.

Authentication Errors
Space & Configuration Errors
Content Operation Errors
Permission Errors
Rate Limiting Errors
Connection Errors
Configuration Errors

Authentication Errors

401: Unauthorized - Invalid API Key

Error message:

Authentication failed: Invalid API key

Causes:

API key doesn't exist or was revoked
API key is incorrectly formatted
Typo in the API key

Solutions:

Verify your API key in the dashboard
Check the format - should start with sb_mcp_
Create a new key if the old one was revoked
Copy/paste carefully to avoid typos
Restart your MCP client after updating the configuration

401: Unauthorized - Missing API Key

Error message:

Authentication failed: API key required

Causes:

X-Api-Key header not provided
Wrong header name
Configuration not loaded

Solutions:

Check your configuration file has the X-Api-Key header:

"headers": {
  "X-Api-Key": "sb_mcp_your_api_key_here"
}

Verify header name is exactly X-Api-Key (case-sensitive)
Restart your MCP client to reload configuration

403: Forbidden - Insufficient Storyblok Permissions

Error message:

Operation not permitted: Your Storyblok token lacks permission to perform this operation

Causes:

Storyblok management token doesn't have required permissions
Token permissions were changed
Wrong token configured

Solutions:

Check token permissions in Storyblok:
- Go to Storyblok → Space Settings → Access Tokens
- Find your BlokMCP management token
- Verify it has the permissions you need
Update token in BlokMCP dashboard:
- Dashboard → Spaces → Edit Space
- Update management token
Common permission requirements:
- Publish: Needs publish permission
- Delete: Needs delete permission
- Schema changes: Needs full or admin access

Space & Configuration Errors

404: Space Not Found

Error message:

Space not found or not configured

Causes:

Space ID in header doesn't match any connected space
Space was disconnected from BlokMCP
Wrong space ID

Solutions:

Check connected spaces in dashboard
Remove X-Storyblok-Space-Id header to use default space
Verify space ID is correct (numeric, from Storyblok URL)
Reconnect space in dashboard if it was disconnected

Multiple Spaces - No Default Set

Error message:

Multiple spaces configured. Please specify which space to use.

Causes:

You have multiple Storyblok spaces connected
No default space is set
No space specified in configuration

Solutions:

Set a default space in the dashboard:
- Dashboard → Spaces
- Click on a space
- Check "Set as default"

Or specify space in configuration:

"headers": {
  "X-Api-Key": "sb_mcp_your_api_key_here",
  "X-Storyblok-Space-Id": "123456"
}

Or ask Claude to specify:
```
Use space ID 123456 for this request
```

See Multi-Space Setup for details.

Content Operation Errors

404: Story Not Found

Error message:

Story not found: ID 123456

Causes:

Story ID doesn't exist
Story was deleted
Wrong space (story is in different space)

Solutions:

Verify story ID - check in Storyblok interface
Search for story instead of using ID:
```
Find the story called "My Story Title"
```
Check you're using the right space

422: Validation Error - Required Fields Missing

Error message:

Validation failed: Field 'title' is required

Causes:

Creating/updating story without required fields
Component schema requires fields that aren't provided

Solutions:

Check required fields for the component:

Show me the schema for the "blog_post" component

Provide all required fields when creating/updating

Ask Claude to check:

Before publishing, verify all required fields are filled

422: Slug Already Exists

Error message:

Validation failed: Slug 'my-story' already exists

Causes:

Trying to create story with duplicate slug
Slug conflicts with existing story

Solutions:

Use a different slug or let Storyblok auto-generate one
Update existing story instead of creating new one

Check for existing story:

Does a story with slug "my-story" already exist?

Permission Errors

Cannot Modify Published Story

Error message:

Cannot modify published story. Unpublish first or create a new version.

Causes:

Trying to edit story that's already published
Workflow rules prevent direct editing

Solutions:

Unpublish first, then edit:

Unpublish the story, update it, then publish again

Or edit and publish in one operation:

Update the story and publish the changes immediately

Workflow Approval Required

Error message:

Operation requires workflow approval

Causes:

Story is in a workflow that requires approval
Trying to publish without going through approval process

Solutions:

Complete approval process in Storyblok

Check workflow status:

What's the workflow status of this story?

Or remove from workflow if not needed

Rate Limiting Errors

429: Rate Limit Exceeded

Error message:

Rate limit exceeded. Please wait 60 seconds before retrying.
Response headers:
  X-RateLimit-Limit: 10
  X-RateLimit-Remaining: 0
  X-RateLimit-Reset: 1234567890

Causes:

Exceeded requests per minute for your subscription tier
Making too many requests too quickly

Your tier limits:

Free: 10 requests/minute, 1,000/month
Pro: 100 requests/minute, 50,000/month
Enterprise: 1,000 requests/minute, 500,000/month

Solutions:

Wait 60 seconds for the rate limit to reset

Slow down bulk operations:

Process 10 stories at a time with a pause between batches

Upgrade subscription for higher limits
Check current usage in dashboard

See Rate Limiting Guide for details.

Connection Errors

Cannot Connect to BlokMCP

Error message:

Failed to connect to https://mcp.blokmcp.com

Causes:

Network connectivity issues
BlokMCP service is down
Firewall blocking connection

Solutions:

Check internet connection
Try accessing blokmcp.com in browser
Check firewall/proxy settings
Wait a few minutes and retry (might be temporary)
Check status page for service status

Connection Timeout

Error message:

Request timeout after 30 seconds

Causes:

Slow network connection
Large operation taking too long
Server under heavy load

Solutions:

Retry the operation
Break into smaller operations if bulk processing
Check network speed

Configuration Errors

Invalid JSON in Configuration File

Error message:

Failed to parse configuration: Unexpected token...

Causes:

Syntax error in JSON configuration file
Missing comma, bracket, or quote
Trailing comma

Solutions:

Validate JSON using a validator:
- Copy/paste into jsonlint.com
- Check for syntax errors
Common mistakes:
- Missing comma between entries
- Extra comma after last entry
- Quotes around keys and values
- Matching braces {}

Example of correct JSON:

{
  "mcpServers": {
    "storyblok": {
      "url": "https://mcp.blokmcp.com",
      "headers": {
        "X-Api-Key": "sb_mcp_..."
      }
    }
  }
}

Configuration File Not Found

Error message:

Configuration file not found

Causes:

File doesn't exist at expected location
Wrong file path
File name incorrect

Solutions:

Create the configuration file at the correct location:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Verify file name is exactly claude_desktop_config.json
Restart your MCP client after creating the file

See Claude Desktop Setup for details.

Getting More Help

Still Having Issues?

Check the docs:

Ask Claude for help:

I'm getting this error: [paste error message].
Can you help me understand what's wrong?

Check dashboard:
Contact support:
- GitHub Issues
- Contact form

Error Code Quick Reference

Code	Meaning	Quick Fix
401	Invalid/missing API key	Check API key in dashboard
403	Insufficient permissions	Update Storyblok token permissions
404	Resource not found	Verify ID/slug exists
422	Validation error	Check required fields
429	Rate limit exceeded	Wait 60 seconds or upgrade plan
500	Server error	Retry or contact support
503	Service unavailable	Wait and retry

Rate Limiting Guide - Detailed rate limit information
API Keys Management - API key documentation
Debugging Tips - Advanced troubleshooting
Multi-Space Setup - Multiple space configuration

Can't find your error? Open an issue or contact us for help!