Troubleshooting Guide

Quick Reference for Common Issues

---

🔍 Diagnostic Decision Tree

Start Here: Is Claude recognizing the MCP server?
├
├─ NO → Issue: MCP Server Not Found
│   │
│   ├─ Config file exists?
│   │   ├─ NO → Create .mcp.json in project root
│   │   └─ YES → Check JSON syntax → Fix errors
│   │
│   ├─ File in correct location?
│   │   └─ Project root directory (.mcp.json)
│   │
│   └─ Claude Code reloaded?
│       └─ NO → Reload window to apply changes
│
└─ YES → Can access Vibe CMS data?
    │
    ├─ NO → Issue: Authentication Failed
    │   │
    │   ├─ Verify Project ID
    │   ├─ Verify API Token
    │   ├─ Check token permissions
    │   └─ Test with new token
    │
    └─ YES → Working! If slow, see Performance section

---

🚨 Issue 1: MCP Server Not Found

Symptoms

• Claude doesn't respond to Vibe CMS commands
• "List all MCP servers" doesn't show vibe-cms-prod
• No Vibe CMS tools available

Root Causes

Cause A: Configuration File Missing or Wrong Location

Check location:

ls -la .mcp.json

If missing: Create the file in your project root with this content:

{
  "mcpServers": {
    "vibe-cms-prod": {
      "command": "npx",
      "args": ["-y", "vibe-cms-mcp-server"],
      "env": {
        "VIBE_PROJECT_ID": "your-project-id",
        "VIBE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cause B: Invalid JSON Syntax

Test with:

# With jq installed
cat .mcp.json | jq .

# Or copy contents to https://jsonlint.com

Common errors:

// ❌ WRONG: Missing comma
{
  "mcpServers": {
    "server1": {}
    "server2": {}
  }
}

// ✅ CORRECT: Comma between entries
{
  "mcpServers": {
    "server1": {},
    "server2": {}
  }
}

// ❌ WRONG: Trailing comma
{
  "mcpServers": {
    "server1": {},
  }
}

// ✅ CORRECT: No trailing comma
{
  "mcpServers": {
    "server1": {}
  }
}

Cause C: Claude Code Not Reloaded

Reload window:

# In Claude Code:
# Press Cmd+Shift+P (macOS) or Ctrl+Shift+P (Windows/Linux)
# Type "Reload Window" and select it
# Or use the reload button in the interface

Verify config loaded:

# In project root
cat .mcp.json

# Should show your MCP server configuration

Cause D: NPX Not Found

Test:

npx --version

If error: Install Node.js from https://nodejs.org

Alternative: Use global install instead:

npm install -g vibe-cms-mcp-server

Update config to:

{
  "command": "vibe-cms-mcp-server",
  "args": []
}

Cause E: MCP Server Not Approved

Symptoms:

• Config file is correct and in the right location
• JSON syntax is valid
• Window has been reloaded multiple times
• Claude Code still doesn't recognize the MCP server

Root Cause: MCP server needs to be explicitly approved by Claude Code before it can be used.

Solution: Run the MCP approval command in terminal:

# From your project root directory
claude mcp

What happens:

1. Command will display your MCP configuration
2. You'll be prompted to approve the MCP server
3. Select "Yes" or "Approve" to allow Claude to use this MCP server
4. Restart Claude Code or reload the window

Why this is needed: For security reasons, Claude Code requires explicit user approval before connecting to any MCP server, even if it's correctly configured in .mcp.json.

When to try this:

• After creating a new .mcp.json file
• After adding a new MCP server to an existing config
• When MCP server isn't loading despite correct configuration
• As a last resort after reloading/restarting hasn't worked

Verification: After approval and reload, run:

"List all available MCP servers"

You should now see your vibe-cms-prod (or your configured server name) in the list.

---

🔐 Issue 2: Authentication Failed

Symptoms

• MCP server found but can't access data
• "Authentication failed" or "Unauthorized" errors
• Can list tools but they return errors

Root Causes

Cause A: Invalid Project ID

Verify:

1. Log in to Vibe CMS dashboard
2. Settings → Project
3. Copy exact Project ID (format: proj_xxxxx)

Common mistakes:

• Extra spaces before/after
• Wrong project (if you have multiple)
• Typos in manual entry

Fix: Update VIBE_PROJECT_ID in .mcp.json with correct value

Cause B: Invalid or Expired Token

Symptoms:

• Worked before, stopped working
• Token looks correct but fails

Solution: Generate new token:

1. Vibe CMS dashboard
2. Settings → API Keys
3. Revoke old token (if exists)
4. Generate new token
5. Copy immediately
6. Update VIBE_API_TOKEN in .mcp.json
7. Reload Claude Code window

Cause C: Insufficient Permissions

Check token permissions:

1. Vibe CMS dashboard
2. Settings → API Keys
3. Click on your token
4. View permissions

Required minimum:

• ✅ Read content
• ✅ Write content
• ✅ Manage files
• ✅ Manage schema

If missing: Create new token with correct permissions

Cause D: Network Connectivity

Test API access directly:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.vibecms.com/v1/projects/YOUR_PROJECT_ID

# Should return JSON with project info
# If error: Check network, firewall, or VPN

Check:

• Internet connection working
• Firewall not blocking API calls
• VPN not interfering
• Corporate proxy settings

---

⚡ Issue 3: Slow Performance

Symptoms

• Commands take >10 seconds
• Timeouts on operations
• Claude appears to hang

Root Causes

Cause A: Large Dataset Queries

Problem: Fetching all content without filters

Bad:

"Show me all blog posts"  // 10,000 posts = slow!

Good:

"Show me the 10 most recent blog posts"  // Much faster

Solution: Always use limits and filters

Cause B: Network Latency

Test latency:

ping api.vibecms.com

# Good: <50ms
# Acceptable: 50-200ms
# Slow: >200ms

If slow:

• Check internet connection
• Try different network
• Contact ISP if persistent

Cause C: Rate Limiting

Symptoms:

• Fast initially, then slows
• "Rate limit exceeded" errors

Check usage:

1. Vibe CMS dashboard
2. Settings → API Usage
3. View current rate limit status

Solution:

• Wait a few minutes
• Upgrade plan if consistently hitting limits
• Implement caching in your app

---

📁 Issue 4: File Upload Problems

Symptoms

• Upload commands fail
• "File too large" errors
• Files upload but don't appear

Root Causes

Cause A: File Size Exceeds Limit

Check limits:

1. Vibe CMS dashboard
2. Settings → Plan Details
3. View file size limits

Solutions:

• Compress images before upload
• Split large files
• Upgrade plan for larger limits

Compress images:

# Example with ImageMagick
convert large.jpg -quality 85 -resize 2000x2000\> optimized.jpg

Cause B: Unsupported File Type

Check file extension: Some types may be restricted

Workaround: Convert to supported format:

• HEIC → JPG
• BMP → PNG
• AVI → MP4

Cause C: Invalid Folder Path

Bad paths:

• //double-slash
• /trailing/slash/
• /special!chars/

Good paths:

• /images
• /blog/2024
• /documents/pdf

Cause D: Storage Quota Exceeded

Check quota:

1. Vibe CMS dashboard
2. Settings → Storage
3. View current usage

Solutions:

• Delete unused files
• Compress existing files
• Upgrade plan

---

🌍 Issue 5: Translation Problems

Symptoms

• Translations not appearing
• Wrong language displayed
• Missing translations

Root Causes

Cause A: Locale Not Created

Verify locales exist:

"List all locales in my project"

If missing:

"Add German (de-DE) as a locale"

Cause B: Content Not Translated

Remember: Creating content creates it in ONE locale only

Check:

"Show me the blog post [id] with all translations"

If missing translation:

"Add a German translation for blog post [id] with..."

Cause C: Default Locale Issues

Check default locale:

1. Vibe CMS dashboard
2. Settings → Locales
3. Verify default is correct

Fallback behavior: If translation missing, uses default locale

Cause D: Locale Code Mismatch

Common mistakes:

• Using de instead of de-DE
• Using en instead of en-US
• Case sensitivity: en-us vs en-US

Standard: Always use BCP 47 format (e.g., en-US, fr-FR)

---

🔄 Issue 6: Changes Not Appearing

Symptoms

• Made changes but don't see them
• Website shows old content
• API returns outdated data

Root Causes

Cause A: Content Still Draft

Check status:

"What is the status of content item [id]?"

If draft:

"Publish content item [id]"

Remember: All edits are to draft version - must publish!

Cause B: Browser Cache

Clear cache:

• Chrome: Cmd/Ctrl + Shift + R (hard refresh)
• Safari: Cmd + Option + R
• Firefox: Cmd/Ctrl + Shift + R

Or: Open in incognito/private window

Cause C: CDN Cache

If using CDN: May need to purge cache

• Cloudflare: Purge cache in dashboard
• Fastly: Purge cache via API
• AWS CloudFront: Invalidate distribution

Typical cache duration: 5-60 minutes

Cause D: Application Cache

If using app-level caching: May need to invalidate

React Query example:

queryClient.invalidateQueries({ queryKey: ['content'] })

General: Restart your dev server

Cause E: Static Site Generation Cache (Astro/Next.js)

Symptoms:

• Updated content in Vibe CMS via MCP or dashboard
• Changes not reflected in local development or production site
• "Stale" content persists even after browser refresh

Root Cause: Static Site Generators (SSG) like Astro fetch content at build time, not runtime. Once built, the HTML contains a snapshot of your content that won't change until you rebuild.

For Local Development (Astro):

1. Hard refresh your browser:

   macOS: Cmd + Shift + R
   Windows/Linux: Ctrl + Shift + R
   

   This clears client-side browser cache.

2. Restart your dev server:

   # Stop the server (Ctrl + C)
   # Then restart:
   npm run dev
   

   This forces Astro to fetch fresh content from Vibe CMS.

3. Why this happens:

   • Astro's dev server caches API responses for performance
   • Content is fetched during page load, not on every request
   • MCP updates in Vibe CMS don't automatically trigger rebuilds

For Production Deployments:

1. Trigger a new build/deployment:

   • Vercel: Push to git or use "Redeploy" button
   • Netlify: Push to git or use "Trigger deploy" button
   • GitHub Pages: Push to git to trigger Actions workflow

2. Webhook-based rebuilds (recommended):

   # Example: Vercel deploy hook
   curl -X POST https://api.vercel.com/v1/integrations/deploy/...
   

   Set up webhooks in Vibe CMS to auto-trigger rebuilds on publish.

3. Manual purge CDN cache (if applicable):

   • After deploying, purge CDN cache to serve fresh content immediately

Prevention Tips:

• Use getStaticPaths() with revalidate in Astro for ISR (Incremental Static Regeneration)
• Implement webhook automation for auto-rebuilds on CMS publish
• Document rebuild process for content editors
• Consider SSR (Server-Side Rendering) for pages that need real-time content

Quick Reference:

# Problem: Content not updating after MCP changes
# Solution 1: Hard refresh browser
Cmd/Ctrl + Shift + R

# Solution 2: Restart dev server
npm run dev

# Solution 3 (Production): Trigger rebuild
git commit --allow-empty -m "Rebuild for content update" && git push

This is expected behavior for SSG frameworks - not a bug! Content updates require rebuilds to be reflected.

---

🛠️ Diagnostic Commands

Check MCP Server Status

"List all available MCP servers"

Expected: Shows vibe-cms-prod or your configured name

Check Authentication

"What is my Vibe CMS project ID?"

Expected: Returns your project ID If error: Authentication problem

List Collections

"Show me all collections in my Vibe CMS project"

Expected: List of collections (or empty if none) If error: Permission or connection problem

Test File Access

"Show me all folders in my Vibe CMS project"

Expected: List of folders (or empty if none) If error: File permission issue

Check Locale Setup

"What locales are configured in my project?"

Expected: List of active locales If empty: Need to add locales

---

📊 Logs and Debugging

View Claude Code Logs

Check logs in IDE:

• View output panel in Claude Code
• Check for MCP server connection messages
• Look for authentication errors

View recent logs:

# Check if MCP server is running
ps aux | grep vibe-cms-mcp-server

Enable Debug Mode

In .mcp.json (if supported):

{
  "env": {
    "VIBE_PROJECT_ID": "proj_xxx",
    "VIBE_API_TOKEN": "token_xxx",
    "VIBE_DEBUG": "true"
  }
}

Test API Directly

Using curl:

# List collections
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.vibecms.com/v1/projects/YOUR_PROJECT_ID/collections

# Get collection schema
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.vibecms.com/v1/projects/YOUR_PROJECT_ID/collections/blog-posts

Expected: JSON response with data If error: Check token, project ID, permissions

---

🔘 When to Contact Support

Contact support if:

• Followed all troubleshooting steps
• Issue persists for >24 hours
• Affects production environment
• Data loss or corruption
• Security concern

Gather before contacting:

1. System info:

   • OS and version
   • Claude Code version
   • Node.js version (node --version)

2. Error details:

   • Exact error messages
   • Steps to reproduce
   • When issue started

3. Configuration (redact tokens!):

   • MCP server config from .mcp.json (remove API token)
   • Project ID (can share)

4. Logs:

   • Relevant log excerpts
   • Redact sensitive information

Contact methods:

• 🔴 Urgent/Production: support@vibecms.com (Subject: URGENT)
• 🟡 General: support@vibecms.com
• 🟢 Questions: Discord or Community Forum

Response times:

• Critical (production down): <2 hours
• High priority: <4 hours
• Normal: <24 hours
• Low priority: <48 hours

---

✅ Prevention Checklist

Prevent issues by:

• Validating JSON before saving .mcp.json
• Keeping API tokens secure and rotated
• Testing changes in staging first
• Monitoring API usage and quotas
• Keeping Claude Code updated
• Documenting your setup
• Regular backups of important content
• Using version control for config templates
• Setting up monitoring/alerts
• Training team on proper workflows

---

📚 Additional Resources

• User Manual - Complete documentation
• Chapter 1: MCP Setup - Detailed installation
• FAQ - Common questions
• Quick Start - Fast setup guide

---

Still stuck? → Email support@vibecms.com with detailed error info

---

Troubleshooting Guide v1.0 | Vibe CMS Documentation