What causes "invalid duration" in kataras/iris?

Provide the value as a number or a valid Go duration string like "300ms" or "1h"

invalid duration

Error message

invalid duration

What it means

TimeNotationDuration.UnmarshalJSON returns 'invalid duration' when the JSON token is neither a number nor a recognized duration string with time notation (e.g. "5s", "2h30m"). Only number and string cases are handled; all other JSON kinds hit the default error branch.

Source

Thrown at x/jsonx/time_notation.go:87

	}

	var v any
	if err := json.Unmarshal(b, &v); err != nil {
		return err
	}
	switch value := v.(type) {
	case float64:
		*d = TimeNotationDuration(value)
		return nil
	case string:
		dv, err := ParseTimeNotationDuration(value)
		if err != nil {
			return err
		}
		*d = dv
		return nil
	default:
		return errors.New("invalid duration")
	}
}

func (d TimeNotationDuration) ToDuration() time.Duration {
	return time.Duration(d)
}

func (d TimeNotationDuration) Value() (driver.Value, error) {
	return d.ToDuration(), nil
}

// Set sets the value of duration in nanoseconds.
func (d *TimeNotationDuration) Set(v float64) {
	if math.IsNaN(v) {
		return
	}

	*d = TimeNotationDuration(v)

View on GitHub (pinned to 7bedaf55a0)

Solutions

Provide the value as a number or a valid Go duration string like "300ms" or "1h"
Correct the JSON field's type in config/payload
Pre-validate the config with a schema or encoding/json dry-run

Example fix

// before
{"interval": "5 minutes"}
// after
{"interval": "5m"}

Defensive patterns

Strategy: validation

Validate before calling

var probe map[string]json.RawMessage
if err := json.Unmarshal(raw, &probe); err != nil { return err }
if v, ok := probe["interval"]; ok && v[0] != '"' && !(v[0] >= '0' && v[0] <= '9') {
    return fmt.Errorf("interval must be number or duration string like \"5s\"")
}

Type guard

func isInvalidTimeNotation(err error) bool { return err != nil && strings.Contains(err.Error(), "invalid duration") }

Try / catch

if err := json.Unmarshal(raw, &cfg); err != nil {
    if strings.Contains(err.Error(), "invalid duration") {
        return fmt.Errorf("use Go duration notation, e.g. \"2h30m\"")
    }
    return err
}

Prevention

Use Go duration string syntax ("300ms", "1h") in configs, never "5 minutes"
Validate configs at startup with a dry-run decode
Keep duration fields flat scalars, never objects/arrays

When it happens

Trigger: Unmarshalling {"interval": [1,2]} or {"interval": true} into a TimeNotationDuration field; a string that the duration parser fails to convert.

Common situations: Config files where a duration field was given as a list or object; unit mistakes such as "5 seconds" (space, wrong unit) instead of "5s".

Related errors

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