Last updated 13 October 2026
Fix JSON errors in Claude CLI output
The nature of JSON parsing errors in the terminal
When you are deep in a coding session, a JSON parsing error is the last thing you want to see. Your terminal might suddenly output a massive block of garbled text or simply freeze while trying to process a tool response. This happens when the communication between the local CLI and the remote model breaks down. The agent might send back a message that contains unescaped characters or a mix of conversational text and structured data. This confuses the local parser which expects a very specific format to render the user interface. You might see errors about unexpected tokens or end-of-file markers that make no sense in the context of your current task.
This problem often occurs when a tool like Bash or Read returns a large amount of data that includes control characters or unusual symbols. The model tries to summarize this data or pass it along, but the formatting gets corrupted along the way. Instead of a clean list of files or a successful edit, you get a screen full of technical debt. It stops your flow and forces you to debug the tool instead of your code. Understanding why this happens is the first step toward preventing it from recurring in your daily workflow. It is usually not a permanent failure of the tool but a temporary mismatch in how data is being packaged and sent over the wire.
Enforcing output standards with project instructions
Your project instructions are the most powerful tool for preventing these errors. Every project should have a CLAUDE.md file in the root directory. This file tells the agent how to behave and what standards to follow. If you find that the agent is frequently breaking the JSON output, you should add specific rules to this file. Tell the agent to be concise and to avoid adding conversational preambles when executing tools. You can also specify that it should never include raw binary data in its responses. By tightening these rules, you reduce the surface area for formatting mistakes.
You can also use nested CLAUDE.md files for more granular control. If you have a directory that contains many configuration files or complex data structures, put a separate instruction file there. This helps the agent understand the specific context of that subfolder. It might need different rules for a folder full of JSON schemas than it does for a folder full of Python scripts. The agent reads the most relevant instruction file first, so you can override global rules with more specific ones where they are needed. This hierarchy of instructions keeps the agent focused and less likely to produce the kind of wandering output that leads to parsing failures.
Clearing the session context to remove corruption
The context window of a session can become cluttered over time. As you run more commands and read more files, the history grows. This history includes every tool call, every error, and every response from the agent. If the session has been running for a long time, the agent might start to mimic previous formatting errors or get confused by the sheer volume of data it has to track. This is often when you start seeing malformed JSON. The agent is trying to reference too many things at once and loses its grip on the required output format.
You have two main ways to handle this within the CLI. The first is the /compact command. This tells the agent to summarize the conversation so far and clear out the old, raw data. This frees up space in the context window and often resolves issues where the agent was getting bogged down by old mistakes. If /compact does not work, you can use the /clear command. This resets the entire session history while keeping you in the same working directory. It is a more drastic step, but it is often necessary when the session has become so corrupted that the agent can no longer follow basic formatting rules. Starting fresh eliminates the baggage that was causing the JSON errors in the first place.
Managing tool outputs for better stability
Tools like Bash and Read are essential for the agent to understand your code, but they can also be the source of JSON issues. If the agent runs a Bash command that produces thousands of lines of output, that output has to be wrapped in a JSON structure to be sent back to the CLI. If that output contains certain characters or is simply too large, the process can fail. You should encourage the agent to use more precise tools like Glob or Grep to find exactly what it needs instead of reading entire files or listing every directory. This keeps the data packets small and less prone to corruption.
When the agent needs to read a file, it uses the Read tool. If that file is a massive JSON or XML file, the agent might try to process the whole thing at once. This can lead to a situation where the agent response becomes a nested mess of data that breaks the terminal ability to render it. You can prevent this by instructing the agent in your CLAUDE.md to only read specific parts of files or to use the Grep tool to search for patterns first. By limiting the amount of raw data the agent handles, you significantly improve the stability of the terminal interface and avoid the dreaded parsing errors that halt your progress.
Visualizing multiple sessions for easier troubleshooting
Monitoring a single terminal window can be difficult when things go wrong. If you are running a long-lived task that involves many tool calls, you might miss the subtle signs that the agent is starting to struggle with its output format. This is where adhdTerminal provides a clear advantage. By running your Claude Code sessions as tiles on a wall, you can see at a glance if a particular session has stalled or is producing strange output. Each tile shows the last few exchanges of the conversation, allowing you to spot JSON formatting issues before they completely break the interface.
The visual nature of the wall helps you manage the cognitive load of dealing with multiple complex tasks. If one session starts showing signs of a JSON error, you can focus on it while your other tasks continue to run in their own tiles. Each tile remembers its state even after a restart, which is useful when you need to step away from a broken session to clear your head. You can see whether a session is working, waiting for your input, or sitting idle. This persistent view means you do not have to keep all the context in your head, turning a chaotic terminal experience into an organized workspace.
Environmental checks and manual updates
If you are seeing consistent JSON errors that do not seem related to your specific code or instructions, the problem might be with the Claude Code installation itself. The CLI is a complex piece of software that interacts with your shell and the remote API. Sometimes, a bug in how the CLI handles certain terminal themes or character sets can lead to rendering issues that look like JSON errors. The first thing you should do is run the command claude doctor in your terminal. This command performs a series of checks to ensure your environment is set up correctly and that the CLI can communicate with the server without issues.
If the doctor command does not find any problems, your next step should be to run claude update. The developers at Anthropic frequently release improvements to the CLI to handle edge cases in tool output and terminal rendering. An update might contain a fix for the exact parsing issue you are experiencing. It is also a good idea to check your terminal settings. Sometimes, specific fonts or encoding settings can interfere with how the CLI displays the structured data coming back from the agent. Ensuring your terminal is set to use UTF-8 and a standard font can resolve many of the visual glitches that appear as malformed JSON.
Manual intervention and permission modes
You are not a passive observer when the agent is working. You have several keys and commands at your disposal to steer the conversation back on track. If you notice the agent is starting to dump a huge amount of unformatted JSON into the terminal, press the Escape key once. This interrupts the agent immediately. It stops the current process and gives you back control so you can redirect the agent or clear the context. If the session has already become unreadable, pressing Escape twice will open a menu that allows you to jump back to an earlier point in the conversation. This is a lifesaver when a single bad turn has corrupted the session state.
You can also change the way the agent approaches tasks by cycling through permission modes. By pressing Shift+Tab, you can move between modes like default, acceptEdits, and plan. In plan mode, the agent describes what it wants to do before it actually executes any tools. This gives you a chance to see if its plan involves a command that might produce too much output or break the formatting. If the plan looks risky, you can tell the agent to modify its approach. Using these modes gives you a layer of oversight that can prevent JSON errors from ever happening. It allows you to catch the problem at the intent stage rather than the execution stage.
Configuring settings and tool permissions
The behavior of Claude Code is governed by several settings files. These files allow you to customize how the agent uses tools and how it handles permissions. If you find that a specific tool, like the Bash tool, is the source of your JSON errors, you can modify your .claude/settings.json file to change its behavior. You can set specific permissions for each tool, choosing to allow them automatically or requiring a prompt every time. This level of control allows you to restrict the agent ability to run commands that are known to produce problematic output.
Settings can be applied at different levels. There is a global configuration in ~/.claude/settings.json that applies to all your projects, and a project-specific one in .claude/settings.json. You can also use .claude/settings.local.json for settings that you do not want to check into version control. This is useful for environment-specific tweaks that might help resolve rendering issues on your particular machine. For example, if you know your local shell has a custom prompt that interferes with tool output, you can try to adjust how the CLI interacts with the terminal in these settings. Managing your configuration properly ensures that the agent operates within the boundaries that work best for your specific development environment.
Questions people ask
How can I revert a session after a JSON parsing error occurs?
You should press the Escape key twice. This opens a history browser that allows you to select an earlier message in the conversation to return to. This effectively rolls back the session state to a point before the malformed JSON corrupted the terminal output.
Can I fix JSON errors without losing my current session history?
The best approach is to use the /compact command. This summarizes the existing conversation and clears out the raw history, which often removes the data patterns causing the agent to produce malformed output. If that fails, you may need to use /clear to start the conversation over in the same directory.
What should I do if claude doctor finds no environmental issues?
Run the command claude update to ensure you are on the latest version of the CLI. If the problem persists, check your root CLAUDE.md file and add instructions that forbid the agent from including raw binary data or conversational filler when using tools like Bash or Read.
Read next
- Access git submodules in Claude CodeFix issues where Claude Code cannot see or modify code located inside nested git submodules within your main repository.
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.