What causes "failed to unmarshal xml: %w" in gofiber/fiber?

Validate the request Content-Type is application/xml and the body is well-formed XML before binding (parse with xml.Unmarshal into a throwaway value or check the prolog).

gofiber/fiber · error

failed to unmarshal xml

Error message

failed to unmarshal xml: %w

What it means

XMLBinding.Bind wraps the underlying utils.XMLUnmarshal error when the request body cannot be decoded into the target struct. The wrapped error carries the raw decoder cause (syntax error, type mismatch, or unexpected EOF).

Solutions

Validate the request Content-Type is application/xml and the body is well-formed XML before binding (parse with xml.Unmarshal into a throwaway value or check the prolog).
Correct the target struct's xml tags to match the document.
If using a custom decoder, return a descriptive error and ensure it is set on XMLBinding.XMLDecoder.

Example fix

// before
var p Payload
if err := xmlBinder.Bind(body, &p); err != nil { ... }

// after
var p Payload
if err := xmlBinder.Bind(body, &p); err != nil {
    if syntaxErr := (*xml.SyntaxError)(nil); errors.As(err, &syntaxErr) {
        return fmt.Errorf("malformed xml from client: %w", err)
    }
    return err
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Cheap pre-check that the body parses as XML before binding:
var probe any
if err := xml.Unmarshal(body, &probe); err != nil {
    return fmt.Errorf("rejecting non-xml body: %w", err)
}

Try / catch

if err := xmlBinder.Bind(body, &out); err != nil {
    var se *xml.SyntaxError
    if errors.As(err, &se) { /* malformed payload */ }
    var te *xml.UnmarshalTypeError
    if errors.As(err, &te) { /* struct/tag mismatch */ }
    return err
}

Prevention

Verify Content-Type is application/xml before attempting XML binding.
Keep struct xml tags in sync with the document; add integration tests using representative payloads.
Reject bodies that exceed a sane max size before decoding to limit attacker-controlled work.

When it happens

Trigger: A client sending malformed XML, truncated body, wrong encoding (e.g. UTF-16 BOM), or a body that does not map onto the out struct's fields/tags. Also triggered if XMLDecoder was replaced with a custom function that itself returns an error.

Common situations: Missing or wrong XML struct tags; client sends JSON with Content-Type: application/xml; partial read truncating the body; a Reset() leaving XMLDecoder nil and a default being supplied that is stricter than expected.

Related errors

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/9e5db863c6beef67. Report an issue: GitHub.

Appendix: source

Thrown at binder/xml.go:22

	"fmt"

	"github.com/gofiber/utils/v2"
)

// XMLBinding is the XML binder for XML request body.
type XMLBinding struct {
	XMLDecoder utils.XMLUnmarshal
}

// Name returns the binding name.
func (*XMLBinding) Name() string {
	return "xml"
}

// Bind parses the request body as XML and returns the result.
func (b *XMLBinding) Bind(body []byte, out any) error {
	if err := b.XMLDecoder(body, out); err != nil {
		return fmt.Errorf("failed to unmarshal xml: %w", err)
	}

	return nil
}

// Reset resets the XMLBinding binder.
func (b *XMLBinding) Reset() {
	b.XMLDecoder = nil
}

View on GitHub (pinned to a105acad6c)