ipfs/kubo · error

invalid priority value: %d

Error message

invalid priority value: %d

What it means

Priority.MarshalJSON in config/types.go serializes the tri-state Priority (DefaultPriority/Disabled) to JSON (null or false). A Priority holding any other internal integer has no JSON representation, so marshaling fails with "invalid priority value: %d". Like Flag, this can only arise from constructing the value programmatically with an out-of-range state.

Source

Thrown at config/types.go:189

			panic(fmt.Sprintf("invalid priority %d < 0", int64(p)))
		}
		return int64(p), true
	}
}

func (p Priority) MarshalJSON() ([]byte, error) {
	// > 0 == Priority
	if p > 0 {
		return json.Marshal(int64(p))
	}
	// <= 0 == special
	switch p {
	case DefaultPriority:
		return json.Marshal(nil)
	case Disabled:
		return json.Marshal(false)
	default:
		return nil, fmt.Errorf("invalid priority value: %d", p)
	}
}

func (p *Priority) UnmarshalJSON(input []byte) error {
	switch string(input) {
	case "null", "undefined":
		*p = DefaultPriority
	case "false":
		*p = Disabled
	case "true":
		return fmt.Errorf("'true' is not a valid priority")
	default:
		var priority int64
		err := json.Unmarshal(input, &priority)
		if err != nil {
			return err
		}
		if priority <= 0 {

View on GitHub (pinned to 329838acdf)

Solutions

1. Assign only config.DefaultPriority or config.Disabled to Priority fields.
2. Zero-initialize Priority values (DefaultPriority marshals to null, meaning default behavior).
3. If importing from user input, decode with Priority.UnmarshalJSON (accepting null/undefined/false) rather than casting integers.

Example fix

// before
cfg.Reprovider.Strategy.Priority = config.Priority(3)
// after
cfg.Reprovider.Strategy.Priority = config.Disabled

func validPriority(p config.Priority) bool { return p == config.DefaultPriority || p == config.Disabled }

func isValidPriority(p config.Priority) bool {
    switch p {
    case config.DefaultPriority, config.Disabled:
        return true
    }
    return false
}

if err := json.Marshal(cfg); err != nil {
    if strings.Contains(err.Error(), "invalid priority value") { /* fix Priority field */ }
    return err
}

When it happens

Trigger: Setting a config.Priority field (e.g. under Reprovider or related config) to an arbitrary integer in Go code (library consumers, tests, generated configs) and then marshaling/writing the config via json.Marshal or WriteConfigFile.

Common situations: kubo-as-a-library code assigning raw ints to Priority fields, reflection-based or fuzz-generated config structs, or porting code from older config versions where priority constants changed.

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 flag 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/90a26fb028789729. Report an issue: GitHub.