What causes "fiber: failed to decode shared state %s value: %w" in gofiber/fiber?

Pass a non-nil pointer to the target type as the `out` argument.

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

Error message

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

What it means

Returned by decodeSharedStateValue (shared_state.go:398) when a configured decoder (JSON/XML/MsgPack/CBOR) returns a non-nil error while deserializing stored bytes into the caller's output value during GetJSON/GetXML/GetMsgPack/GetCBOR. The format and original error are wrapped via %w.

Source

Thrown at shared_state.go:398

		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()
		}()

		err = decoder(data, out)
	}()

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

	return nil
}

func sharedStateCodecNotConfiguredError(format, direction string) error {
	return fmt.Errorf("fiber: shared state %s %s is not configured", format, direction)
}

func sharedStateCodecPanicError(operation, format string, recovered any) error {
	if err, ok := recovered.(error); ok {
		return fmt.Errorf("fiber: failed to %s shared state %s value: %w", operation, format, err)
	}

	return fmt.Errorf("fiber: failed to %s shared state %s value: %v", operation, format, recovered)
}

func (s *SharedState) storageKey(key string) (string, bool) {

View on GitHub (pinned to 9a4c7e57fe)

Solutions

Pass a non-nil pointer to the target type as the `out` argument.
Verify the stored bytes match the expected format — dump and inspect them.
Align struct tags / types between writer and reader; migrate stored data on schema changes.
If using a custom decoder, test it against the raw bytes in isolation.

Example fix

// before: schema mismatch + non-pointer
var v OldShape
_, _, err := state.GetJSON(ctx, "k", v)

// after: matching schema, pointer target
var v CurrentShape
_, ok, err := state.GetJSON(ctx, "k", &v)
if err != nil { return err }
if !ok { /* not stored */ }

Defensive patterns

Strategy: validation

Validate before calling

var out Target
if rv := reflect.ValueOf(out); rv.Kind() != reflect.Ptr || rv.IsNil() {
    return errors.New("out must be a non-nil pointer")
}
_, _, err := state.GetJSON(ctx, "k", &out)

Type guard

func isNonNilPointer(v any) bool {
    rv := reflect.ValueOf(v)
    return rv.Kind() == reflect.Ptr && !rv.IsNil()
}

Try / catch

if _, _, err := state.GetJSON(ctx, "k", &out); err != nil {
    if strings.Contains(err.Error(), "failed to decode") {
        // schema mismatch or corrupt payload — migrate or re-store
    }
}

Prevention

Always pass a non-nil pointer as the out argument.
Keep reader/writer struct schemas in sync; migrate stored data on changes.
Dump and validate stored bytes when decode errors appear.

When it happens

Trigger: Calling GetJSON/GetXML/etc. where the stored bytes are malformed for the format, the target type does not match what was stored (schema drift), or a nil/non-pointer out argument causes the decoder to fail. The decoder error from shared_state.go:391 is captured.

Common situations: Stored payload written by a different encoder version (schema change), corrupted storage, reading JSON into a struct whose fields changed, passing a non-pointer or nil pointer as `out`, or a custom decoder rejecting the payload.

Related errors

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