From 9d08bbc67e9c6a2234b3e66acc11ad536ee49f8a Mon Sep 17 00:00:00 2001 From: RubenPari Date: Sat, 8 Aug 2026 09:57:17 +0200 Subject: [PATCH 1/2] fix(binding): include field name in BindUnmarshaler errors Wrap UnmarshalParam / parser errors with the form tag so clients see which field failed (e.g. "uuid4: boom") without breaking %w. Fixes #4296 --- binding/form_mapping.go | 24 ++++++++++++++++-------- binding/form_mapping_test.go | 17 +++++++++++++++++ 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/binding/form_mapping.go b/binding/form_mapping.go index 6982fd4f..ada227c1 100644 --- a/binding/form_mapping.go +++ b/binding/form_mapping.go @@ -196,6 +196,14 @@ func trySetCustom(val string, value reflect.Value) (isSet bool, err error) { return false, nil } +// wrapBindErr prefixes a bind error with the form/query field name. +func wrapBindErr(fieldName string, err error) error { + if err == nil || fieldName == "" { + return err + } + return fmt.Errorf("%s: %w", fieldName, err) +} + // trySetUsingParser tries to set a custom type value based on the presence of the "parser" tag on the field. // If the parser tag does not exist or does not match any of the supported parsers, gin will skip over this. func trySetUsingParser(val string, value reflect.Value, parser string) (isSet bool, err error) { @@ -264,9 +272,9 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][ } if ok, err = trySetUsingParser(vs[0], value, opt.parser); ok { - return ok, err + return ok, wrapBindErr(tagValue, err) } else if ok, err = trySetCustom(vs[0], value); ok { - return ok, err + return ok, wrapBindErr(tagValue, err) } if vs, err = trySplit(vs, field); err != nil { @@ -289,9 +297,9 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][ } if ok, err = trySetUsingParser(vs[0], value, opt.parser); ok { - return ok, err + return ok, wrapBindErr(tagValue, err) } else if ok, err = trySetCustom(vs[0], value); ok { - return ok, err + return ok, wrapBindErr(tagValue, err) } if vs, err = trySplit(vs, field); err != nil { @@ -312,9 +320,9 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][ } if ok, err = trySetUsingParser(val, value, opt.parser); ok { - return ok, err + return ok, wrapBindErr(tagValue, err) } else if ok, err = trySetCustom(val, value); ok { - return ok, err + return ok, wrapBindErr(tagValue, err) } return true, setWithProperType(val, value, field, opt) } @@ -323,9 +331,9 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][ func setWithProperType(val string, value reflect.Value, field reflect.StructField, opt setOptions) error { // this if-check is required for parsing nested types like []MyId, where MyId is [12]byte if ok, err := trySetUsingParser(val, value, opt.parser); ok { - return err + return wrapBindErr(field.Name, err) } else if ok, err = trySetCustom(val, value); ok { - return err + return wrapBindErr(field.Name, err) } // If it is a string type, no spaces are removed, and the user data is not modified here diff --git a/binding/form_mapping_test.go b/binding/form_mapping_test.go index c78f7398..f8196724 100644 --- a/binding/form_mapping_test.go +++ b/binding/form_mapping_test.go @@ -505,6 +505,23 @@ func (f *customUnmarshalParamHex) UnmarshalParam(param string) error { return nil } +type failUnmarshalParam struct{} + +func (f *failUnmarshalParam) UnmarshalParam(param string) error { + return errors.New("boom") +} + +func TestBindUnmarshalerErrorIncludesFieldName(t *testing.T) { + var s struct { + ID failUnmarshalParam `form:"uuid4"` + } + err := mappingByPtr(&s, formSource{"uuid4": {"xxx"}}, "form") + require.Error(t, err) + assert.Contains(t, err.Error(), "uuid4") + assert.Contains(t, err.Error(), "boom") + assert.ErrorContains(t, err, "boom") // still unwrap-friendly via %w +} + func TestMappingCustomUnmarshalParamHexWithFormTag(t *testing.T) { var s struct { Foo customUnmarshalParamHex `form:"foo"` From 4ae0c0f019fcf17a9fce3a77cadaa91e09fb3578 Mon Sep 17 00:00:00 2001 From: RubenPari Date: Mon, 28 Sep 2026 11:04:05 +0200 Subject: [PATCH 2/2] fix(binding): use the tag value for every bind error prefix Carry the resolved tag value (or the Go field name when the tag is empty) in setOptions so pointer fields and slice/array elements, which go through setWithProperType, get the same prefix as the direct path. Rename wrapBindErr to prefixBindErr and cover query tags, pointers, slices, nested structs, the TextUnmarshaler parser, the no-parser path and nil errors. Co-Authored-By: Claude Opus 5.5 --- binding/form_mapping.go | 30 ++++++++++----- binding/form_mapping_test.go | 75 ++++++++++++++++++++++++++++++++---- 2 files changed, 88 insertions(+), 17 deletions(-) diff --git a/binding/form_mapping.go b/binding/form_mapping.go index ada227c1..1fb5d539 100644 --- a/binding/form_mapping.go +++ b/binding/form_mapping.go @@ -140,6 +140,8 @@ type setOptions struct { defaultValue string // parser specifies what interface to use for reading the request & default values (e.g. `encoding.TextUnmarshaler`) parser string + // fieldName is the tag value (or the Go field name when the tag is empty) used to prefix bind errors + fieldName string } func tryToSetValue(value reflect.Value, field reflect.StructField, setter setter, tag string) (bool, error) { @@ -176,6 +178,7 @@ func tryToSetValue(value reflect.Value, field reflect.StructField, setter setter } } + setOpt.fieldName = tagValue return setter.TrySet(value, field, tagValue, setOpt) } @@ -196,8 +199,8 @@ func trySetCustom(val string, value reflect.Value) (isSet bool, err error) { return false, nil } -// wrapBindErr prefixes a bind error with the form/query field name. -func wrapBindErr(fieldName string, err error) error { +// prefixBindErr prefixes a bind error with the form/query field name. +func prefixBindErr(fieldName string, err error) error { if err == nil || fieldName == "" { return err } @@ -255,6 +258,9 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][ if !ok && !opt.isDefaultExists { return false, nil } + if opt.fieldName == "" { + opt.fieldName = tagValue + } switch value.Kind() { case reflect.Slice: @@ -272,9 +278,9 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][ } if ok, err = trySetUsingParser(vs[0], value, opt.parser); ok { - return ok, wrapBindErr(tagValue, err) + return ok, prefixBindErr(opt.fieldName, err) } else if ok, err = trySetCustom(vs[0], value); ok { - return ok, wrapBindErr(tagValue, err) + return ok, prefixBindErr(opt.fieldName, err) } if vs, err = trySplit(vs, field); err != nil { @@ -297,9 +303,9 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][ } if ok, err = trySetUsingParser(vs[0], value, opt.parser); ok { - return ok, wrapBindErr(tagValue, err) + return ok, prefixBindErr(opt.fieldName, err) } else if ok, err = trySetCustom(vs[0], value); ok { - return ok, wrapBindErr(tagValue, err) + return ok, prefixBindErr(opt.fieldName, err) } if vs, err = trySplit(vs, field); err != nil { @@ -320,20 +326,24 @@ func setByForm(value reflect.Value, field reflect.StructField, form map[string][ } if ok, err = trySetUsingParser(val, value, opt.parser); ok { - return ok, wrapBindErr(tagValue, err) + return ok, prefixBindErr(opt.fieldName, err) } else if ok, err = trySetCustom(val, value); ok { - return ok, wrapBindErr(tagValue, err) + return ok, prefixBindErr(opt.fieldName, err) } return true, setWithProperType(val, value, field, opt) } } func setWithProperType(val string, value reflect.Value, field reflect.StructField, opt setOptions) error { + // fieldName is set by tryToSetValue; the Go field name only covers direct calls. + if opt.fieldName == "" { + opt.fieldName = field.Name + } // this if-check is required for parsing nested types like []MyId, where MyId is [12]byte if ok, err := trySetUsingParser(val, value, opt.parser); ok { - return wrapBindErr(field.Name, err) + return prefixBindErr(opt.fieldName, err) } else if ok, err = trySetCustom(val, value); ok { - return wrapBindErr(field.Name, err) + return prefixBindErr(opt.fieldName, err) } // If it is a string type, no spaces are removed, and the user data is not modified here diff --git a/binding/form_mapping_test.go b/binding/form_mapping_test.go index f8196724..3474c9d5 100644 --- a/binding/form_mapping_test.go +++ b/binding/form_mapping_test.go @@ -505,21 +505,82 @@ func (f *customUnmarshalParamHex) UnmarshalParam(param string) error { return nil } +var errBoom = errors.New("boom") + type failUnmarshalParam struct{} func (f *failUnmarshalParam) UnmarshalParam(param string) error { - return errors.New("boom") + return errBoom +} + +type failUnmarshalText string + +func (f *failUnmarshalText) UnmarshalText(text []byte) error { + return errBoom } func TestBindUnmarshalerErrorIncludesFieldName(t *testing.T) { - var s struct { + var formTag struct { ID failUnmarshalParam `form:"uuid4"` } - err := mappingByPtr(&s, formSource{"uuid4": {"xxx"}}, "form") - require.Error(t, err) - assert.Contains(t, err.Error(), "uuid4") - assert.Contains(t, err.Error(), "boom") - assert.ErrorContains(t, err, "boom") // still unwrap-friendly via %w + var queryTag struct { + ID failUnmarshalParam `query:"uuid4"` + } + var pointer struct { + ID *failUnmarshalParam `form:"uuid4"` + } + var slice struct { + IDs []failUnmarshalParam `form:"uuid4"` + } + var nested struct { + Inner struct { + ID failUnmarshalParam `form:"uuid4"` + } + } + var noTag struct { + ID failUnmarshalParam + } + var textParser struct { + ID failUnmarshalText `form:"uuid4,parser=encoding.TextUnmarshaler"` + } + + tests := []struct { + name string + ptr any + tag string + want string + }{ + {"form tag", &formTag, "form", "uuid4: boom"}, + {"query tag", &queryTag, "query", "uuid4: boom"}, + {"pointer field", &pointer, "form", "uuid4: boom"}, + {"slice element", &slice, "form", "uuid4: boom"}, + {"nested struct", &nested, "form", "uuid4: boom"}, + {"TextUnmarshaler parser", &textParser, "form", "uuid4: boom"}, + {"no tag falls back to field name", &noTag, "form", "ID: boom"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + form := formSource{"uuid4": {"xxx"}, "ID": {"xxx"}} + err := mappingByPtr(tt.ptr, form, tt.tag) + require.EqualError(t, err, tt.want) + require.ErrorIs(t, err, errBoom) + }) + } +} + +func TestBindUnmarshalerErrorNotPrefixedWithoutParser(t *testing.T) { + // Without a parser tag, UnmarshalText is not used and the value is set as a plain string. + var s struct { + ID failUnmarshalText `form:"uuid4"` + } + require.NoError(t, mappingByPtr(&s, formSource{"uuid4": {"xxx"}}, "form")) + assert.Equal(t, failUnmarshalText("xxx"), s.ID) +} + +func TestPrefixBindErr(t *testing.T) { + require.NoError(t, prefixBindErr("uuid4", nil)) + assert.Equal(t, errBoom, prefixBindErr("", errBoom)) + require.EqualError(t, prefixBindErr("uuid4", errBoom), "uuid4: boom") } func TestMappingCustomUnmarshalParamHexWithFormTag(t *testing.T) {