kataras/iris · warning · ErrInvalid

%w: season: %s

Error message

%w: season: %s

What it means

Season is a bitmask (Winter=1, Spring=2, Summer=4, Autumn=8; 0 means AllSeasons). During UnmarshalJSON, after converting the JSON number to an int, IsValid() (s&AllSeasons==s) rejects any value that uses bits outside 1..15, wrapping ErrInvalid as "invalid: season: %s" with the original JSON text.

Source

Thrown at x/jsonx/season.go:119

	data = trimQuotes(data)
	if len(data) == 0 {
		return nil
	}

	str := string(data)
	constantAsInt, err := strconv.Atoi(str)
	if err != nil {
		return err
	}

	if constantAsInt == 0 { // if 0 is passed, it means All seasons.
		constantAsInt = int(AllSeasons)
	}

	*s = Season(constantAsInt)
	if !s.IsValid() {
		return fmt.Errorf("%w: season: %s", ErrInvalid, str)
	}

	return nil
}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Send a valid bitmask value: 0/15 for all, 1..15 for combinations (e.g. 3 = Winter|Spring).
2. Validate the integer on the client before sending (0 <= v <= 15, or v == 0).
3. Accept the JSON as a number and construct with jsonx.Season(v) + IsValid() check on your side to produce a friendlier message.

Example fix

// before
{"season": 16} // invalid
// after
{"season": 15} // AllSeasons
// or combine: 1|4 = 5 -> "Winter, Summer"

func validSeasonJSON(v int) bool { return v >= 0 && v <= 15 }
// or with the library type: jsonx.Season(v).IsValid()

func parseSeason(v int) (jsonx.Season, bool) {
	s := jsonx.Season(v)
	if v == 0 {
		s = jsonx.AllSeasons
	}
	return s, s.IsValid()
}

var p Payload
if err := json.Unmarshal(data, &p); err != nil {
	if errors.Is(err, jsonx.ErrInvalid) && strings.Contains(err.Error(), "season") {
		return fmt.Errorf("season must be a bitmask 0-15: %w", err)
	}
	return err
}

When it happens

Trigger: Unmarshaling JSON like {"season": 16}, {"season": 32}, or any negative number into a struct field of type jsonx.Season.

Common situations: Client sending a wrong/out-of-range enum value; frontend treating season as a plain enum instead of a bitmask; API version drift where new bit values are invented.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• kitchen time: dest is nil
• invalid duration
• invalid duration
• %w: example: %s
• ErrNotFound

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/fe89295c4bd05657. Report an issue: GitHub.