ipfs/kubo · error

invalid flag value: %d

Error message

invalid flag value: %d

What it means

Flag.MarshalJSON in config/types.go marshals the tri-state Flag (Default/True/False) to JSON. If the Flag holds an out-of-range integer value that is none of the three defined states, marshaling fails with "invalid flag value: %d". This indicates the Flag was constructed programmatically with an invalid value, since JSON unmarshaling cannot produce one.

Source

Thrown at config/types.go:89

	case Default:
		return defaultValue
	case True:
		return true
	default:
		panic(fmt.Sprintf("invalid flag value %d", f))
	}
}

func (f Flag) MarshalJSON() ([]byte, error) {
	switch f {
	case Default:
		return json.Marshal(nil)
	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 {

View on GitHub (pinned to 329838acdf)

Solutions

1. Only assign the exported constants config.Default, config.True, or config.False to Flag fields.
2. Zero-initialize Flags (config.Default is the zero state that marshals to null).
3. If the value comes from user input, parse it with Flag.UnmarshalJSON (accepting null/true/false) instead of casting.

Example fix

// before
cfg.Provider.Enabled = config.Flag(7)
// after
cfg.Provider.Enabled = config.True

func validFlag(f config.Flag) bool { return f == config.Default || f == config.True || f == config.False }

func isValidFlag(f config.Flag) bool {
    switch f {
    case config.Default, config.True, config.False:
        return true
    }
    return false
}

if err := json.Marshal(cfg); err != nil {
    var fe *json.MarshalerError
    if errors.As(err, &fe) && strings.Contains(fe.Error(), "invalid flag value") { /* fix Flag field */ }
    return err
}

When it happens

Trigger: Building a kubo Config struct in Go (e.g. a library consumer or test) and assigning an arbitrary integer to a config.Flag field, then serializing it with json.Marshal or writing it via WriteConfigFile/serialize.

Common situations: Custom node-construction code (kubo-as-a-library) setting Flag fields with raw integers instead of config.Default/config.True/config.False; fuzzing or reflection-based config generation producing bogus values.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• invalid priority value: %d
• failure to decode config: %w
• failed to unmarshal %q into a flag: must be null/undefined,
• mountFuse: GetConfig() failed: %s
• %s path cannot be empty

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