Claude Code Error: Unexpected Token in JSON Response Fix

The “unexpected token in JSON” error is one of the most common issues developers encounter when working with Claude Code. This error typically occurs when Claude attempts to parse a response that isn’t valid JSON, breaking the communication pipeline between the AI and your tools. Understanding the root causes and having a toolkit of solutions ready will save you hours of frustration.

What Causes This Error

When Claude Code makes tool calls or interacts with external services, it expects JSON-formatted responses. The “unexpected token” error surfaces when the response contains malformed JSON—either from a tool output, an API call, or a skill that returns improperly formatted data.

Common scenarios triggering this error include:

API endpoints returning HTML or plain text instead of JSON
Tool outputs containing special characters that break JSON parsing
Custom skills returning markdown-formatted content instead of structured data
Network responses with encoding issues or truncated data

Diagnosis Techniques

Before applying fixes, identify where the malformed JSON originates. Start by examining the error message itself—Claude Code usually indicates which tool or skill produced the invalid response.

Use the Read tool to inspect recent tool outputs in your conversation history. Look for responses that contain:

Unescaped quotes or special characters
Markdown formatting code blocks
Incomplete JSON objects or arrays
Non-UTF8 encoded characters

If you’re using custom skills, check the skill definition for any double-curly-brace or percent-curly-brace Liquid template syntax that might interfere with JSON parsing.

Practical Solutions

Solution 1: Validate API Responses

When calling external APIs, ensure they return valid JSON:

import requests
import json

def call_api(url):
    response = requests.get(url)
    # Force JSON parsing to catch errors early
    try:
        data = response.json()
        return data
    except json.JSONDecodeError as e:
        print(f"Invalid JSON response: {e}")
        print(f"Response text: {response.text[:200]}")
        raise

This approach catches malformed responses before they reach Claude’s parsing layer.

Solution 2: Escape Special Characters in Tool Outputs

If your tool produces text with quotes or special characters, escape them properly:

# Instead of echoing raw JSON
echo '{"message": "Here's a quote"}'  # Breaks!

# Use proper escaping
echo '{"message": "Here'"'"'s a quote"}'
# Or use printf
printf '{"message": "Here'\''s a quote"}\n'

For more complex scenarios, consider using a JSON library to generate properly escaped output.

Solution 3: Configure Your Skills Correctly

When creating custom skills using tools like the skill-creator, ensure your skill definitions don’t interfere with JSON parsing. Avoid placing unescaped curly braces in skill descriptions:

---
name: my-skill
description: Processes data using the (variable) pattern
# This causes issues! Use escaped brackets or rephrase
---

Instead, structure your skill descriptions without template variables that could confuse the JSON parser.

Working with Claude Skills

Claude skills like pdf, tdd, and frontend-design often interact with external tools and APIs. When these skills produce errors, the “unexpected token” issue frequently stems from how they handle their outputs.

For instance, when using the pdf skill to generate documents from markdown, ensure your markdown doesn’t contain inline JSON-like patterns that get misinterpreted. The docx skill handles similar scenarios by providing clearer output formatting.

The supermemory skill may encounter this error when storing or retrieving metadata. Always validate the data structure before passing it to skills that expect specific JSON schemas.

Prevention Strategies

Implement Response Validation

Create a wrapper function that validates all responses before they reach Claude:

function validateJsonResponse(response) {
  try {
    const parsed = JSON.parse(response);
    return { valid: true, data: parsed };
  } catch (error) {
    return { 
      valid: false, 
      error: error.message,
      raw: response.substring(0, 100)
    };
  }
}

Use Type-Safe APIs

When building integrations, prefer APIs that guarantee JSON responses. Check documentation for content-type headers and implement fallback handling for non-JSON responses.

Test Skills in Isolation

Before deploying custom skills to production, test them with varied inputs using the xlsx skill to validate JSON outputs across different data scenarios. This is particularly important for skills that handle user-generated content.

Error Recovery

When you encounter this error during a session:

Pause the current operation - Don’t continue with potentially corrupted data
Identify the source - Check which tool or skill produced the invalid response
Clear and retry - Use Claude Code’s reset capability to clear the problematic context
Fix the root cause - Apply the appropriate solution from above
Resume with validation - Implement checks to prevent recurrence

Conclusion

The “unexpected token in JSON response” error is manageable once you understand its origins and have a systematic approach to debugging. By validating API responses, properly escaping special characters, and carefully configuring your skills, you can prevent this error from disrupting your workflow.

Remember to test your integrations thoroughly, especially when combining multiple skills like supermemory with custom API calls. Most importantly, always implement error handling that catches JSON parsing failures early—before they reach Claude Code’s processing layer.

Claude Skill Invalid YAML Syntax Error: How to Debug — See also
Claude Skill YAML Front Matter Parsing Error Fix — See also
Skill MD File Format Explained With Examples — See also
Claude Skills Troubleshooting Hub — See also

Built by theluckystrike — More at zovo.one