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

Fix the custom codec to panic with errors, or better, return errors instead of panicking.

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

Error message

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

What it means

Returned by sharedStateCodecPanicError (shared_state.go:413) when a configured shared-state encoder/decoder PANICS with a value that is NOT an error (e.g. a string, a custom struct). Because recovered.(error) fails, Fiber formats the panic value with %v rather than %w. The operation (encode/decode) and format are still named.

Source

Thrown at shared_state.go:413

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

Solutions

Fix the custom codec to panic with errors, or better, return errors instead of panicking.
Replace the codec with a standard implementation that returns errors.
Inspect the %v string in the message to locate the offending panic site in your codec.
Add unit tests around the codec with the failing input type.

Example fix

// before: codec panics with a string
func badEnc(v any) ([]byte, error) {
    if v == nil { panic("nil not allowed") }
    ...
}

// after: return an errorunc badEnc(v any) ([]byte, error) {
    if v == nil { return nil, errors.New("nil not allowed") }
    ...
}

Defensive patterns

Strategy: try-catch

Try / catch

if err := state.SetMsgPack(ctx, "k", v, ttl); err != nil {
    // a non-error panic value was recovered; inspect message %v text
    log.Printf("codec panic: %v", err)
}

Prevention

Custom codecs should return errors, never panic with primitives.
Wrap any unavoidable panic values as errors via panic(fmt.Errorf(...)).
Unit-test codecs against nil and unsupported inputs.

When it happens

Trigger: A custom codec panics with panic("some string") or panic(42) or panic(MyStruct{...}) instead of an error. The recover catches it, the type assertion to error fails (shared_state.go:409), so the %v branch at shared_state.go:413 fires.

Common situations: Hand-written codec that does panic("unsupported type") instead of returning an error; a third-party library that panics with non-error values; misuse of panic with primitive types.

Related errors

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