gofiber/fiber · error

fiber: failed to shared state value

Error message

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

What it means

Thrown by sharedStateCodecPanicError when a user-configured codec (encoder/decoder for SharedState, e.g. JSON, Msgpack) panics while serializing/deserializing a shared-state value, and the recovered panic value implements error. Fiber wraps the original error so the caller can see both the operation (encode/decode), the format, and the root cause. It surfaces only when Config app/shared-state serialization is in use and the codec itself is buggy or receives a non-serializable value.

Solutions

1. Inspect the wrapped error (%w) to identify the underlying codec failure and fix the value or the codec.
2. Ensure every value stored in SharedState is of a type your configured codec can round-trip (e.g. plain structs/maps for JSON, msgp-generated types for msgp).
3. If using a custom codec, audit its encode/decode for panics on edge-case inputs and return errors instead of panicking.
4. Add a unit test that encodes then decodes each value type you intend to store, to catch regressions before runtime.

Example fix

// before: storing a value the codec cannot serialize
app.State().Set("conn", liveDBConn)

// after: store only serializable descriptors
app.State().Set("connInfo", map[string]string{"dsn": dsn})

// Verify each value is round-trippable before storing it
func safeSet(state *fiber.SharedState, key string, val any, codec Codec) error {
    b, err := codec.Encode(val)
    if err != nil { return fmt.Errorf("encode %s: %w", key, err) }
    var back any
    if err := codec.Decode(b, &back); err != nil { return fmt.Errorf("decode %s: %w", key, err) }
    state.Set(key, val)
    return nil
}

// Reject values known to be non-serializable before they reach SharedState
func isSerializable(v any) bool {
    rv := reflect.ValueOf(v)
    switch rv.Kind() {
    case reflect.Chan, reflect.Func, reflect.Invalid:
        return false
    }
    return true
}

// Wrap state operations that go through a user codec
func safeDecode(codec Codec, b []byte, dst any) (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("codec panic: %v", r)
        }
    }()
    return codec.Decode(b, dst)
}

When it happens

Trigger: A SharedState codec (set via app config) panics during Acquire/Release of a state value; the panic value is an error type. This happens inside the recover() block of the encode/decode wrapper, so it appears as a returned error from the state operation rather than a crash.

Common situations: Registering a custom codec that calls json.Marshal on a value containing a channel/func; msgp-generated codec fed a type it was not generated for; version mismatch where the codec library changed its error type; passing a non-serializable struct into ctx.Locals or shared state.

Related errors

• fiber: failed to shared state value
• fiber: failed to encode shared state
• fiber: shared state is not configured
• cache: failed to marshal key
• cache: failed to unmarshal key

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

Appendix: source

Thrown at shared_state.go:410

	}()

	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) {
	if key == "" {
		return "", false
	}

	return s.prefix + hex.EncodeToString(utils.UnsafeBytes(key)), true
}

View on GitHub (pinned to a105acad6c)