gofiber/fiber · error

fiber: failed to encode shared state

Error message

fiber: failed to encode shared state %s value: %w

What it means

Returned by encodeSharedStateValue() when the configured encoder (json/msgpack/cbor/xml) returns a non-nil error while serializing a value for SharedState.SetJSON/SetMsgPack/SetCBOR/SetXML. Fiber also recovers panics from the codec separately (sharedStateCodecPanicError); this error is the non-panic failure path.

Solutions

1. Inspect the wrapped error — encoders name the offending field/type.
2. Add a MarshalJSON/MarshalBinary method or remove the unserializable field (chan, func, io.Reader).
3. For XML, ensure map keys are string-convertible or use a slice of structs.
4. Unit-test marshaling of every type you store in SharedState.

Example fix

// before — struct with a chan field cannot be JSON-encoded
type Job struct{ ID string; Done chan struct{} }
app.State().Shared().SetJSON("job:1", Job{ID: "1", Done: make(chan struct{})}, 0)
// -> fiber: failed to encode shared state json value: json: unsupported type: chan struct {}

// after — drop the unserializable field or provide a custom marshaler
type Job struct{ ID string }
app.State().Shared().SetJSON("job:1", Job{ID: "1"}, 0)

// Encode a representative value at startup to fail fast.
func validateEncodable(enc func(any) ([]byte, error), sample any) error {
    if _, err := enc(sample); err != nil {
        return fmt.Errorf("value not encodable: %w", err)
    }
    return nil
}

// Reject types known to be unserializable before storing.
func encodableForJSON(v any) bool {
    rv := reflect.ValueOf(v)
    switch rv.Kind() {
    case reflect.Chan, reflect.Func, reflect.Invalid:
        return false
    }
    return true
}

if err := app.State().Shared().SetJSON(k, v, ttl); err != nil {
    log.Printf("shared state encode failed for %s: %v", k, err)
    return fiber.ErrInternalServerError
}

When it happens

Trigger: Calling app.State().Shared().SetJSON(key, v, ttl) (or MsgPack/CBOR/XML variants) where v cannot be marshaled: a channel, func, or cyclic reference for JSON; an XML-incompatible type (map with non-string keys); a type whose MarshalBinary/MarshalJSON returns an error.

Common situations: Storing a struct that embeds an unexported type the codec refuses; switching a value type after deployment to one the codec cannot serialize; a custom MarshalJSON that errors on a nil receiver; passing an io.Reader or chan field.

Related errors

• fiber: failed to decode shared state
• fiber: shared state is not configured
• failed to encode data
• failed to encode session data
• failed to marshal response

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

Appendix: source

Thrown at shared_state.go:368

		err       error
		recovered any
	)
	func() {
		// App-configured codecs may be nil or may still use Fiber's
		// binder.Unimplemented* placeholders, which panic instead of returning an
		// error, so recover here and surface a regular error.
		defer func() {
			recovered = recover()
		}()

		encoded, err = encoder(v)
	}()

	if recovered != nil {
		return nil, sharedStateCodecPanicError("encode", format, recovered)
	}
	if err != nil {
		return nil, fmt.Errorf("fiber: failed to encode shared state %s value: %w", format, err)
	}

	return encoded, nil
}

func decodeSharedStateValue(data []byte, out any, decoder func([]byte, any) error, format string) error {
	if decoder == nil {
		return sharedStateCodecNotConfiguredError(format, "decoder")
	}

	var (
		err       error
		recovered any
	)
	func() {
		// App-configured codecs may be nil or may still use Fiber's
		// binder.Unimplemented* placeholders, which panic instead of returning an
		// error, so recover here and surface a regular error.

View on GitHub (pinned to a105acad6c)