What causes "priority must be positive: %d <= 0" in ipfs/kubo?

Q: What causes "priority must be positive: %d <= 0" in ipfs/kubo?

Set Priority to a positive integer (>= 1).

priority must be positive: %d <= 0

Error message

priority must be positive: %d <= 0

What it means

The Priority type requires a strictly positive integer; UnmarshalJSON parses the JSON number and returns this error when the value is zero or negative. Priorities in kubo config are ranks where higher means more important, so 0 or negative values are meaningless and rejected.

Source

Thrown at config/types.go:208

	}
}

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 {
			return fmt.Errorf("priority must be positive: %d <= 0", priority)
		}
		*p = Priority(priority)
	}
	return nil
}

func (p Priority) String() string {
	if p > 0 {
		return fmt.Sprintf("%d", p)
	}
	switch p {
	case DefaultPriority:
		return "default"
	case Disabled:
		return "false"
	default:
		return fmt.Sprintf("<invalid priority %d>", p)
	}

View on GitHub (pinned to 329838acdf)

Solutions

Set Priority to a positive integer (>= 1).
To disable, use the value "false" instead of 0.
Validate the JSON with `ipfs config --json` before writing config.json directly.

Example fix

// before
{"Priority": 0}
// after
{"Priority": 1}   // or "false" to disable

Defensive patterns

Strategy: validation

Validate before calling

func checkPriority(n int64) error {
    if n <= 0 {
        return fmt.Errorf("priority must be > 0, got %d (use \"false\" to disable)", n)
    }
    return nil
}

Type guard

func isPositivePriority(v any) bool { n, ok := v.(float64); return ok && n > 0 }

Try / catch

if err := json.Unmarshal(data, &cfg); err != nil {
    var perr *json.UnmarshalTypeError
    if strings.Contains(err.Error(), "priority must be positive") {
        // coerce to 1 or "false" and retry
    }
}

Prevention

Treat 0 as 'disabled' signal and emit "false" instead in config generators
Clamp computed priorities to >= 1 before writing config
Sanity-check generated config with `ipfs config show` in CI

When it happens

Trigger: Unmarshaling {"Priority": 0} or {"Priority": -3} into a config Priority field.

Common situations: Hand-edited config.json with Priority set to 0 assuming it means 'default' or 'off'; scripts computing priorities that can produce zero or negatives; copying values from another config format.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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