What causes "fiber: shared storage is not configured" in gofiber/fiber?

Set Config.SharedStorage to a Storage implementation (e.g. redis.New(), arangodb.New(), memory.New()) when creating the App.

gofiber/fiber · error · ErrSharedStorageNotConfigured

fiber: shared storage is not configured

Error message

fiber: shared storage is not configured

What it means

Declared as ErrSharedStorageNotConfigured in shared_state.go and returned by every SharedState method (Set/Get/SetJSON/Has/Delete/Reset/Close and their *WithContext variants) via ensureStorage when app.config.SharedStorage is nil. SharedState is a cross-instance key/value layer that requires a Storage backend (e.g. Redis, badger, memory) to function; without one there is nowhere to read or write.

Source

Thrown at shared_state.go:17

package fiber

import (
	"context"
	"encoding/hex"
	"encoding/json"
	"encoding/xml"
	"errors"
	"fmt"
	"time"

	"github.com/gofiber/utils/v2"
)

const defaultSharedStatePrefix = "gofiber-shared-state-"

var ErrSharedStorageNotConfigured = errors.New("fiber: shared storage is not configured")

type SharedState struct {
	storage        Storage
	jsonEncoder    utils.JSONMarshal
	jsonDecoder    utils.JSONUnmarshal
	msgPackEncoder utils.MsgPackMarshal
	msgPackDecoder utils.MsgPackUnmarshal
	cborEncoder    utils.CBORMarshal
	cborDecoder    utils.CBORUnmarshal
	xmlEncoder     utils.XMLMarshal
	xmlDecoder     utils.XMLUnmarshal
	prefix         string
}

func newSharedState(cfg *Config) *SharedState {
	if cfg == nil {
		cfg = &Config{}
	}

View on GitHub (pinned to 9a4c7e57fe)

Solutions

Set Config.SharedStorage to a Storage implementation (e.g. redis.New(), arangodb.New(), memory.New()) when creating the App.
Guard callers: check the returned error and degrade gracefully (e.g. fall back to local State()) if shared state is optional.
For tests, inject an in-memory storage so SharedState methods don't error.

Example fix

// before
app := fiber.New()
app.SharedState().Set(ctx, "k", v, ttl) // returns ErrSharedStorageNotConfigured

// after
app := fiber.New(fiber.Config{
    SharedStorage: redis.New(redis.Config{Addr: ":6379"}),
})
app.SharedState().SetWithContext(ctx, "k", v, ttl)

Defensive patterns

Strategy: validation

Validate before calling

// Wire Config.SharedStorage at App construction time.
app := fiber.New(fiber.Config{
    SharedStorage: redis.New(redis.Config{Addr: ":6379"}),
})

Try / catch

if err := app.SharedState().SetWithContext(ctx, "k", v, ttl); err != nil {
    if errors.Is(err, fiber.ErrSharedStorageNotConfigured) {
        // shared state unavailable — degrade to in-process State() or fail gracefully
        return nil
    }
    return err
}

Prevention

Always set Config.SharedStorage when you intend to use SharedState().
Don't confuse State() (per-process) with SharedState() (cross-instance, needs Storage).
In tests, inject an in-memory Storage to satisfy SharedState callers.

When it happens

Trigger: Calling app.SharedState().* (or app.State().SharedState equivalent) without having set Config.SharedStorage when constructing the App. Happens when developers assume State() and SharedState() are interchangeable — State() is in-process, SharedState() needs a configured backend.

Common situations: Adopting the SharedState API for multi-instance coordination and forgetting the Storage dependency; confusing fiber.New()'s per-request storage with SharedState; running tests without wiring a storage stub.

Related errors

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