{"record":{"id":"967792b7d13f9a21","repo":"chroma-core/chroma","slug":"unable-to-decode-configuration-from-json-string","errorCode":null,"errorMessage":"Unable to decode configuration from JSON string: {json_str}","messagePattern":"Unable to decode configuration from JSON string: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/api/configuration.py","lineNumber":185,"sourceCode":"        if definition.is_static:\n            raise StaticParameterError(f\"Cannot set static parameter: {name}\")\n        if not definition.validator(value):\n            raise ValueError(f\"Invalid value for parameter {name}: {value}\")\n        parameter.value = value\n\n    @override\n    def to_json_str(self) -> str:\n        \"\"\"Returns the JSON representation of the configuration.\"\"\"\n        return json.dumps(self.to_json())\n\n    @classmethod\n    @override\n    def from_json_str(cls, json_str: str) -> Self:\n        \"\"\"Returns a configuration from the given JSON string.\"\"\"\n        try:\n            config_json = json.loads(json_str)\n        except json.JSONDecodeError:\n            raise ValueError(\n                f\"Unable to decode configuration from JSON string: {json_str}\"\n            )\n        return cls.from_json(config_json) if config_json else cls()\n\n    @override\n    def to_json(self) -> Dict[str, Any]:\n        \"\"\"Returns the JSON compatible dictionary representation of the configuration.\"\"\"\n        json_dict = {\n            name: parameter.value.to_json()\n            if isinstance(parameter.value, ConfigurationInternal)\n            else parameter.value\n            for name, parameter in self.parameter_map.items()\n        }\n        # What kind of configuration is this?\n        json_dict[\"_type\"] = self.__class__.__name__\n        return json_dict\n\n    @classmethod","sourceCodeStart":167,"sourceCodeEnd":203,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/api/configuration.py#L167-L203","documentation":"ConfigurationInternal.from_json_str (chromadb/api/configuration.py:185) raises this ValueError when json.loads fails on the input string. It is a plain decode failure before any configuration logic runs: the string is not valid JSON (truncated, empty, BOM or encoding issues, single quotes, trailing commas). The original JSONDecodeError is swallowed and re-raised with the offending string embedded in the message.","triggerScenarios":"Passing a truncated or empty string, a file read in binary mode (bytes with BOM), Python-repr dicts (single quotes) instead of JSON, or strings assembled by concatenation with a trailing comma.","commonSituations":"Config strings stored in env vars or databases getting clipped; writing dicts with str(dict) instead of json.dumps; encoding mismatches after file transfers (BOM, latin-1 bytes).","solutions":["Parse-then-pass: call json.loads yourself in a try/except json.JSONDecodeError to get line/column diagnostics, fix the payload, then hand the parsed dict to from_json","If you must use from_json_str, wrap it and catch ValueError; log the string length and first bytes to find truncation","Produce the string only via to_json_str()/json.dumps so it is guaranteed well-formed"],"exampleFix":"# before\ncfg = HNSWConfigurationInternal.from_json_str(raw)   # raw is truncated/invalid\n# after\nimport json\ntry:\n    parsed = json.loads(raw)\nexcept json.JSONDecodeError as e:\n    raise ValueError(f\"bad config JSON at line {e.lineno} col {e.colno}\") from e\ncfg = HNSWConfigurationInternal.from_json(parsed) if parsed else HNSWConfigurationInternal()","handlingStrategy":"try-catch","validationCode":"import json\n\ndef parse_config_str(raw: str):\n    try:\n        return json.loads(raw)\n    except json.JSONDecodeError as e:\n        raise ValueError(f\"malformed config JSON: {e.msg} at line {e.lineno}\") from e","typeGuard":null,"tryCatchPattern":"import json\n\ntry:\n    cfg = Cls.from_json_str(raw)\nexcept ValueError as e:\n    if \"Unable to decode\" in str(e):\n        parsed = json.loads(raw.strip().lstrip(\"\\ufeff\"))  # fix BOM/whitespace\n        cfg = Cls.from_json(parsed) if parsed else Cls()\n    else:\n        raise","preventionTips":["Always produce config strings via to_json_str()/json.dumps","Validate JSON yourself first to get precise line/col diagnostics","Beware truncation when configs travel through env vars or DB text columns"],"tags":["chromadb","configuration","json","deserialization"],"backgroundTag":"configuration-validation-failed","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}