labstack/echo · error

failed to parse value, err: %w

Error message

failed to parse value, err: %w

What it means

Returned by echo.ParseValueOr (binder_generic.go:398-401) — and propagated from ParseValue — when bindValue fails to convert the string into type T. The wrapped error is the underlying strconv/time/Unmarshal failure identifying the real cause.

Source

Thrown at binder_generic.go:400

//   - uint
//   - uint8/byte
//   - uint16
//   - uint32
//   - uint64
//   - string
//   - echo.BindUnmarshaler interface
//   - encoding.TextUnmarshaler interface
//   - json.Unmarshaler interface
//   - time.Duration
//   - time.Time use echo.TimeOpts or echo.TimeLayout to set time parsing configuration
func ParseValueOr[T any](value string, defaultValue T, opts ...any) (T, error) {
	if len(value) == 0 {
		return defaultValue, nil
	}
	var tmp T
	if err := bindValue(value, &tmp, opts...); err != nil {
		var zero T
		return zero, fmt.Errorf("failed to parse value, err: %w", err)
	}
	return tmp, nil
}

func bindValue(value string, dest any, opts ...any) error {
	// NOTE: if this function is ever made public the dest should be checked for nil
	// values when dealing with interfaces
	if len(opts) > 0 {
		if _, isTime := dest.(*time.Time); !isTime {
			return fmt.Errorf("options are only supported for time.Time, got %T", dest)
		}
	}

	switch d := dest.(type) {
	case *bool:
		n, err := strconv.ParseBool(value)
		if err != nil {
			return err

View on GitHub (pinned to 05489dc173)

Solutions

1. Sanitise the string before parsing (trim, drop thousands separators, normalise decimal point)
2. Return a field-level 400 to the client naming the offending field
3. Implement BindUnmarshaler on a custom type to control parsing

Example fix

// before
n, err := echo.ParseValue[int]("12a")
// after
s := strings.TrimSpace("12a")
s = strings.ReplaceAll(s, ",", "")
n, err := echo.ParseValue[int](s)

if _, err := strconv.ParseInt(strings.TrimSpace(value), 10, 64); err != nil {
    return c.JSON(http.StatusBadRequest, map[string]string{"page": "must be an integer"})
}

v, err := echo.ParseValue[T](raw)
if err != nil {
    return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
}

When it happens

Trigger: ParseValue[int]("abc") (strconv.ParseInt fails); ParseValue[float64]("1,5") (comma decimal); ParseValue[time.Duration]("5x") (bad unit); a custom BindUnmarshaler returning an error.

Common situations: Untrusted query/form values that don't match the target scalar type; locale-specific number formats; bad duration units.

Related errors

• binding element must be a struct
• query/param/form tags are not allowed with anonymous struct
• unknown type
• binding to multipart.FileHeader struct is not supported, use
• %s: %w

AI-assisted analysis of labstack/echo@05489dc173 (2026-08-04). Data as JSON: /data/errors/4e40facef03fcb75.json. Report an issue: GitHub.