Debugging Tips

Learn how to troubleshoot common issues and debug problems with BlokMCP.

Reading Error Messages

Common Error Types

404 Not Found

Story not found: ID 123456

Story doesn't exist
Wrong space selected
Story was deleted

403 Forbidden

Insufficient permissions

Token lacks required permissions
Space access denied
Operation not allowed in current plan

422 Validation Error

Validation failed: title is required

Missing required fields
Invalid data format
Constraint violation

429 Rate Limit

Too many requests

Exceeded requests/minute limit
Need to wait or upgrade plan

Diagnostic Steps

Step 1: Verify Basics

Check:
1. Is my API key valid?
2. Am I connected to the right space?
3. Does the story/asset/component exist?
4. Do I have the right permissions?

Step 2: Isolate the Problem

Test with simple operation:
"Get story 123456"

If that works, gradually add complexity:
"Get story 123456 and update title"

Step 3: Check Recent Changes

What changed recently:
- New API key?
- Component schema updated?
- Permissions changed?
- Space settings modified?

Common Issues

Issue: "Story not found"

Possible causes:

Wrong story ID
Different space selected
Story was deleted
Story in different branch

Debug:

"List all stories in this folder to verify IDs"
"Which space am I currently using?"
"Search for story by title instead of ID"

Issue: "Permission denied"

Possible causes:

Token expired or revoked
Insufficient token permissions
Space access removed
Operation requires higher plan tier

Debug:

"Verify my current permissions"
"Check my subscription tier"
"Try a simpler operation (read-only)"

Issue: "Validation failed"

Possible causes:

Missing required fields
Invalid field values
Schema constraints violated
Component structure changed

Debug:

"Show me the component schema"
"What fields are required?"
"Get the current story to see existing values"

Getting Help

Information to Provide

When asking for help, include:

What you're trying to do
Exact error message
Steps you've already tried
Your subscription tier
Relevant IDs (story, component, space)

Example Help Request

I'm trying to publish story 123456 but getting:
"Error 422: Validation failed - featured_image is required"

I've checked and the story does have a featured_image field filled in.
I'm on the Pro plan.
This worked yesterday but started failing today.

Can you help debug this?

Debugging Workflows

Component Issues

1. "Show me the component schema for blog_post"
2. "Get story 123 to see its current structure"
3. "Compare to a working story with same component"
4. Identify differences
5. Fix inconsistencies

Workflow/Publishing Issues

1. "Show me the current workflow stage for story 123"
2. "What permissions does my role have?"
3. "What workflow stage allows publishing?"
4. Move story through proper stages

Asset Upload Issues

1. Check file size (under limits?)
2. Check file type (allowed format?)
3. Check folder permissions
4. Try uploading to different folder
5. Verify storage quota not exceeded

Preventive Measures

Test in dev first - Don't test in production
Start small - Test with one item before bulk operations
Verify before deleting - Double-check before destructive operations
Keep backups - Export important content regularly
Document changes - Track what changed and when

Still stuck? Describe your issue to Claude with full details, and Claude will help troubleshoot!