{"record":{"id":"259f2ce14f3cb39b","repo":"FoundationAgents/MetaGPT","slug":"read-json-file-json-file-failed","errorCode":null,"errorMessage":"read json file: {json_file} failed","messagePattern":"read json file: (.+?) failed","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"metagpt/utils/common.py","lineNumber":580,"sourceCode":"        # Log an error message with the function name, time since start, attempt number, and the exception\n        i.error(\n            f\"Finished call to '{fn_name}' after {sec_format % retry_state.seconds_since_start}(s), \"\n            f\"this was the {_utils.to_ordinal(retry_state.attempt_number)} time calling it. \"\n            f\"exp: {retry_state.outcome.exception()}\"\n        )\n\n    return log_it\n\n\ndef read_json_file(json_file: str, encoding: str = \"utf-8\") -> list[Any]:\n    if not Path(json_file).exists():\n        raise FileNotFoundError(f\"json_file: {json_file} not exist, return []\")\n\n    with open(json_file, \"r\", encoding=encoding) as fin:\n        try:\n            data = json.load(fin)\n        except Exception:\n            raise ValueError(f\"read json file: {json_file} failed\")\n    return data\n\n\ndef handle_unknown_serialization(x: Any) -> str:\n    \"\"\"For `to_jsonable_python` debug, get more detail about the x.\"\"\"\n\n    if inspect.ismethod(x):\n        tip = f\"Cannot serialize method '{x.__func__.__name__}' of class '{x.__self__.__class__.__name__}'\"\n    elif inspect.isfunction(x):\n        tip = f\"Cannot serialize function '{x.__name__}'\"\n    elif hasattr(x, \"__class__\"):\n        tip = f\"Cannot serialize instance of '{x.__class__.__name__}'\"\n    elif hasattr(x, \"__name__\"):\n        tip = f\"Cannot serialize class or module '{x.__name__}'\"\n    else:\n        tip = f\"Cannot serialize object of type '{type(x).__name__}'\"\n\n    raise TypeError(tip)","sourceCodeStart":562,"sourceCodeEnd":598,"githubUrl":"https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/metagpt/utils/common.py#L562-L598","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Validate the file independently: python -m json.tool < file to see the exact decode error and position.","If encoding is the issue, pass the correct encoding, e.g. read_json_file(path, encoding='utf-8-sig').","Restore/regenerate the file from its source if it was truncated by an interrupted write.","Write JSON atomically (write temp file + rename) in producers to avoid partial files."],"exampleFix":"# before\ndata = read_json_file(p)  # file has BOM -> UnicodeDecodeError -> ValueError\n\n# after\ndata = read_json_file(p, encoding='utf-8-sig')","handlingStrategy":"try-catch","validationCode":"import json\nfrom pathlib import Path\n\ndef json_valid(path: str, enc: str = \"utf-8\") -> bool:\n    try:\n        with open(path, encoding=enc) as f:\n            json.load(f)\n        return True\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    data = read_json_file(path, encoding=\"utf-8-sig\")\nexcept ValueError:\n    # locate error with: python -m json.tool; repair or regenerate the file","preventionTips":["Write JSON atomically (temp file + os.replace) to avoid partial files.","Use utf-8-sig when files may carry a BOM.","Validate with python -m json.tool after hand edits."],"tags":["metagpt","json","file-io","encoding","corrupt-file"],"backgroundTag":null,"analyzedSha":"11cdf466d042aece04fc6cfd13b28e1a70341b1f","analyzedAt":"2026-08-14T23:20:02.994Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}