{"record":{"id":"38d43cee11c12cc0","repo":"ipfs/kubo","slug":"failed-to-unmarshal-q-into-a-flag-must-be-null-u","errorCode":null,"errorMessage":"failed to unmarshal %q into a flag: must be null/undefined, true, or false","messagePattern":"failed to unmarshal %q into a flag: must be null/undefined, true, or false","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"config/types.go","lineNumber":102,"sourceCode":"\tcase True:\n\t\treturn json.Marshal(true)\n\tcase False:\n\t\treturn json.Marshal(false)\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"invalid flag value: %d\", f)\n\t}\n}\n\nfunc (f *Flag) UnmarshalJSON(input []byte) error {\n\tswitch string(input) {\n\tcase \"null\":\n\t\t*f = Default\n\tcase \"false\":\n\t\t*f = False\n\tcase \"true\":\n\t\t*f = True\n\tdefault:\n\t\treturn fmt.Errorf(\"failed to unmarshal %q into a flag: must be null/undefined, true, or false\", string(input))\n\t}\n\treturn nil\n}\n\nfunc (f Flag) String() string {\n\tswitch f {\n\tcase Default:\n\t\treturn \"default\"\n\tcase True:\n\t\treturn \"true\"\n\tcase False:\n\t\treturn \"false\"\n\tdefault:\n\t\treturn fmt.Sprintf(\"<invalid flag value %d>\", f)\n\t}\n}\n\n// ResolveBoolFromConfig returns the resolved boolean value based on:","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/ipfs/kubo/blob/329838acdfafae224582930457efe80aa217afc0/config/types.go#L84-L120","documentation":"Flag.UnmarshalJSON accepts only the JSON literals null/undefined, true, and false for a tri-state config.Flag. Any other JSON input (numbers, strings, arrays) fails with this error naming the offending raw input. It exists so config files can distinguish 'unset/default' (null) from explicit true/false.","triggerScenarios":"Writing a non-boolean, non-null JSON value to a Flag config field, e.g. \"EnableManagement\": \"true\" (a string), 1, or an object, then loading the config or running `ipfs config --json` with a quoted/incorrect value.","commonSituations":"Quoting boolean values in config.json by mistake (`\"true\"` instead of `true`), scripts substituting 0/1 for booleans, or templating tools emitting \"undefined\" as a bare word with whitespace/casing issues.","solutions":["Replace the value with a bare JSON true, false, or null in the config file.","Use `ipfs config --json <key> true` (unquoted boolean) rather than hand-editing.","Note that 'null' and 'undefined' both map to Default; use one of those to reset a flag to its default."],"exampleFix":"// before (config.json)\n\"Experimental\": { \"StrategicProviding\": \"true\" }\n// after\n\"Experimental\": { \"StrategicProviding\": true }","handlingStrategy":"validation","validationCode":"var raw json.RawMessage = json.RawMessage(input)\nswitch string(raw) {\ncase \"null\", \"undefined\", \"true\", \"false\":\n    // ok\ndefault:\n    return fmt.Errorf(\"flag fields accept only null/undefined/true/false, got %s\", raw)\n}","typeGuard":null,"tryCatchPattern":"if err := json.Unmarshal(data, &cfg); err != nil {\n    if strings.Contains(err.Error(), \"failed to unmarshal\") {\n        log.Fatalf(\"check boolean config fields (must be true/false/null, not quoted): %v\", err)\n    }\n    return err\n}","preventionTips":["Never quote booleans in config.json: use true, not \"true\"","Use `ipfs config --json key true` for unquoted values","Use null to reset a flag to Default instead of inventing values"],"tags":["config","json","go","unmarshaling"],"backgroundTag":"invalid-json-type","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"}