failed to unmarshal %q into a flag: must be null/undefined,

Error message

failed to unmarshal %q into a flag: must be null/undefined, true, or false

What it means

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.

Source

Thrown at config/types.go:102

	case True:
		return json.Marshal(true)
	case False:
		return json.Marshal(false)
	default:
		return nil, fmt.Errorf("invalid flag value: %d", f)
	}
}

func (f *Flag) UnmarshalJSON(input []byte) error {
	switch string(input) {
	case "null":
		*f = Default
	case "false":
		*f = False
	case "true":
		*f = True
	default:
		return fmt.Errorf("failed to unmarshal %q into a flag: must be null/undefined, true, or false", string(input))
	}
	return nil
}

func (f Flag) String() string {
	switch f {
	case Default:
		return "default"
	case True:
		return "true"
	case False:
		return "false"
	default:
		return fmt.Sprintf("<invalid flag value %d>", f)
	}
}

// ResolveBoolFromConfig returns the resolved boolean value based on:

View on GitHub (pinned to 329838acdf)

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.

Example fix

// before (config.json)
"Experimental": { "StrategicProviding": "true" }
// after
"Experimental": { "StrategicProviding": true }

Defensive patterns

Strategy: validation

Validate before calling

var raw json.RawMessage = json.RawMessage(input)
switch string(raw) {
case "null", "undefined", "true", "false":
    // ok
default:
    return fmt.Errorf("flag fields accept only null/undefined/true/false, got %s", raw)
}

Try / catch

if err := json.Unmarshal(data, &cfg); err != nil {
    if strings.Contains(err.Error(), "failed to unmarshal") {
        log.Fatalf("check boolean config fields (must be true/false/null, not quoted): %v", err)
    }
    return err
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/38d43cee11c12cc0. Report an issue: GitHub.