{"record":{"id":"dece020e782fc02a","repo":"ipfs/kubo","slug":"failed-to-unmarshal-json-s","errorCode":null,"errorMessage":"failed to unmarshal json. %s","messagePattern":"failed to unmarshal json\\. (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"core/commands/config.go","lineNumber":152,"sourceCode":"\t\t\t\tid, err := nodePeerID(r)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t\tgot, err := peer.Decode(candidate)\n\t\t\t\tif err != nil || got != id {\n\t\t\t\t\treturn errors.New(\"cannot set Identity.PeerID to a value that does not match the node's private key; use 'ipfs key rotate' to change the node identity\")\n\t\t\t\t}\n\t\t\t\toutput, err = setConfig(r, key, id.String())\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t\treturn cmds.EmitOnce(res, output)\n\t\t\t}\n\n\t\t\tif parseJSON, _ := req.Options[configJSONOptionName].(bool); parseJSON {\n\t\t\t\tvar jsonVal any\n\t\t\t\tif err := json.Unmarshal([]byte(value), &jsonVal); err != nil {\n\t\t\t\t\terr = fmt.Errorf(\"failed to unmarshal json. %s\", err)\n\t\t\t\t\treturn err\n\t\t\t\t}\n\n\t\t\t\toutput, err = setConfig(r, key, jsonVal)\n\t\t\t} else if isbool, _ := req.Options[configBoolOptionName].(bool); isbool {\n\t\t\t\toutput, err = setConfig(r, key, value == \"true\")\n\t\t\t} else {\n\t\t\t\toutput, err = setConfig(r, key, value)\n\t\t\t}\n\t\t} else {\n\t\t\t// Check if user wants to expand auto values for getter\n\t\t\texpandAuto, _ := req.Options[configExpandAutoName].(bool)\n\t\t\tif expandAuto {\n\t\t\t\toutput, err = getConfigWithAutoExpand(r, key)\n\t\t\t} else {\n\t\t\t\toutput, err = getConfig(r, key)\n\t\t\t}\n\t\t}","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/core/commands/config.go#L134-L170","documentation":"When `ipfs config <key> <value> --json` is given, Kubo parses the value string with encoding/json into an `any` before storing it. If the string is not valid JSON, the raw parse error is wrapped as 'failed to unmarshal json. %s' and the config is left unchanged.","triggerScenarios":"`ipfs config <key> <value> --json` where value is not valid JSON: single quotes (shell-stripped), unquoted bare words (`ipfs config Datastore.StorageMax 10GB --json`), unquoted keys, trailing commas, or shell-mangled quotes in a nested object.","commonSituations":"Shell quoting pitfalls: `--json '{\"a\":1}'` losing inner quotes, forgetting that bare strings must be JSON-quoted (`--json '\"true\"'`), scripts passing env vars that contain unescaped content; also users of the RPC `/api/v0/config` with the json flag.","solutions":["Validate the value first: `echo '<value>' | jq empty` and only then pass it to ipfs config --json","Quote the value as a whole: ipfs config Addresses.API '\"/ip4/127.0.0.1/tcp/5001\"' --json","If the value is a plain string/boolean, drop --json (or use --bool) and pass it raw","Inspect the exact parse error after 'failed to unmarshal json.' — it names the byte offset and problem"],"exampleFix":"// before\n$ ipfs config Datastore.StorageMax 10GB --json\nfailed to unmarshal json. invalid character '1'...\n// after\n$ ipfs config Datastore.StorageMax '\"10GB\"' --json","handlingStrategy":"validation","validationCode":"echo \"$value\" | jq empty && ipfs config \"$key\" \"$value\" --json","typeGuard":"func validJSON(s string) bool { var v any; return json.Unmarshal([]byte(s), &v) == nil }","tryCatchPattern":"if err := run(\"ipfs\", \"config\", key, val, \"--json\"); err != nil {\n\tif strings.Contains(err.Error(), \"failed to unmarshal json\") {\n\t\t// fall back: pass as plain string without --json\n\t}\n}","preventionTips":["Pipe values through `jq empty` before passing with --json","Remember bare strings/numbers still need JSON quoting ('\"10GB\"', '\"true\"')","Use single quotes around the whole value in shells to preserve inner double quotes","Prefer --bool for booleans and plain arguments for strings instead of --json"],"tags":["config","json","cli","parsing"],"backgroundTag":"json-unmarshal-failed","analyzedSha":"329838acdfafae224582930457efe80aa217afc0","analyzedAt":"2026-09-03T18:30:52.135Z","contentChangedAt":"2026-09-03T18:30:52.135Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}