gofiber/fiber · error

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

Error message

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

What it means

Returned by encodeSharedStateValue (shared_state.go:368) when a configured encoder (JSON/XML/MsgPack/CBOR) returns a non-nil error while serializing a value for SetJSON/SetXML/SetMsgPack/SetCBOR. The format name (e.g. 'json') and the original encoder error are wrapped via %w so the caller can diagnose marshalling problems.

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 9a4c7e57fe)

Solutions

1. Reproduce the encode in isolation: json.Marshal(v) directly to see the exact marshal error.
2. Add the required struct tags (json:"...") / make fields exported / remove unsupported types (chan, func, complex).
3. If using a custom encoder (cfg.JSONEncoder etc.), verify it handles your type; fall back to json.Marshal to confirm.
4. For msgpack/cbor, register custom types or use a serializable representation.

Example fix

// before: unserializable field
type S struct { fn func() }
_ = state.SetJSON(ctx, "k", S{}, time.Minute)

// after: serializable shape
type S struct { Name string `json:"name"` }
if err := state.SetJSON(ctx, "k", S{Name: "x"}, time.Minute); err != nil {
    return err
}

if _, err := json.Marshal(v); err != nil {
    return fmt.Errorf("pre-check encode failed: %w", err)
}
_ = state.SetJSON(ctx, "k", v, ttl)

if err := state.SetJSON(ctx, "k", v, ttl); err != nil {
    if strings.Contains(err.Error(), "failed to encode") {
        // serialization issue — fix the type or tags
    }
}

When it happens

Trigger: Calling app.SharedState SetJSON/SetXML/SetMsgPack/SetCBOR with a value the configured encoder cannot serialize — e.g. a struct with unexported fields for JSON, a channel/func field, a recursive struct, a map with non-string keys, or a type missing XML tags.

Common situations: Custom JSONEncoder replacement that rejects types stdlib json accepts; msgpack/cbor encoders that do not support certain Go types; passing an interface{} holding an unserializable concrete type; version upgrade of the encoder library adding stricter validation.

Related errors

• fiber: failed to decode shared state %s value: %w
• fiber: shared state %s %s is not configured
• paginate: failed to encode cursor values
• cache: failed to unmarshal key %q: %w
• cache: failed to marshal key %q: %w

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/141b6ba2cc1384d5.json. Report an issue: GitHub.