FoundationAgents/MetaGPT · error · ValueError

read json file: {json_file} failed

Error message

read json file: {json_file} failed

What it means

read_json_file in metagpt/utils/common.py opens the file and calls json.load inside a bare try, converting ANY exception during parsing into ValueError('read json file: ... failed'). This covers JSONDecodeError (malformed JSON) as well as UnicodeDecodeError from a wrong encoding parameter.

Source

Thrown at metagpt/utils/common.py:580

        # Log an error message with the function name, time since start, attempt number, and the exception
        i.error(
            f"Finished call to '{fn_name}' after {sec_format % retry_state.seconds_since_start}(s), "
            f"this was the {_utils.to_ordinal(retry_state.attempt_number)} time calling it. "
            f"exp: {retry_state.outcome.exception()}"
        )

    return log_it


def read_json_file(json_file: str, encoding: str = "utf-8") -> list[Any]:
    if not Path(json_file).exists():
        raise FileNotFoundError(f"json_file: {json_file} not exist, return []")

    with open(json_file, "r", encoding=encoding) as fin:
        try:
            data = json.load(fin)
        except Exception:
            raise ValueError(f"read json file: {json_file} failed")
    return data


def handle_unknown_serialization(x: Any) -> str:
    """For `to_jsonable_python` debug, get more detail about the x."""

    if inspect.ismethod(x):
        tip = f"Cannot serialize method '{x.__func__.__name__}' of class '{x.__self__.__class__.__name__}'"
    elif inspect.isfunction(x):
        tip = f"Cannot serialize function '{x.__name__}'"
    elif hasattr(x, "__class__"):
        tip = f"Cannot serialize instance of '{x.__class__.__name__}'"
    elif hasattr(x, "__name__"):
        tip = f"Cannot serialize class or module '{x.__name__}'"
    else:
        tip = f"Cannot serialize object of type '{type(x).__name__}'"

    raise TypeError(tip)

View on GitHub (pinned to 11cdf466d0)

Solutions

  1. Validate the file independently: python -m json.tool < file to see the exact decode error and position.
  2. If encoding is the issue, pass the correct encoding, e.g. read_json_file(path, encoding='utf-8-sig').
  3. Restore/regenerate the file from its source if it was truncated by an interrupted write.
  4. Write JSON atomically (write temp file + rename) in producers to avoid partial files.

Example fix

# before
data = read_json_file(p)  # file has BOM -> UnicodeDecodeError -> ValueError

# after
data = read_json_file(p, encoding='utf-8-sig')
Defensive patterns

Strategy: try-catch

Validate before calling

import json
from pathlib import Path

def json_valid(path: str, enc: str = "utf-8") -> bool:
    try:
        with open(path, encoding=enc) as f:
            json.load(f)
        return True
    except Exception:
        return False

Try / catch

try:
    data = read_json_file(path, encoding="utf-8-sig")
except ValueError:
    # locate error with: python -m json.tool; repair or regenerate the file

Prevention

When it happens

Trigger: Truncated JSON (interrupted write); JSON with trailing commas, comments, or single quotes; UTF-16/BOM files read with the default encoding='utf-8'; two writers appending to the same file producing concatenated objects.

Common situations: A crashed previous run left a half-written file; the JSON was hand-edited and broke syntax; file saved on Windows with BOM or a different encoding than the encoding= argument passed in.

Related errors

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/259f2ce14f3cb39b. Report an issue: GitHub.