caddyserver/caddy · error

loading TLS storage module: %s

Error message

loading TLS storage module: %s

What it means

The distributed STEK provider's Provision loads the optional custom storage module (Provider.Storage) via ctx.LoadModule; failure is wrapped as 'loading TLS storage module'. This happens when the configured storage module name is unknown or the module itself fails to provision.

Source

Thrown at modules/caddytls/distributedstek/distributedstek.go:78

}

// CaddyModule returns the Caddy module information.
func (Provider) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:  "tls.stek.distributed",
		New: func() caddy.Module { return new(Provider) },
	}
}

// Provision provisions s.
func (s *Provider) Provision(ctx caddy.Context) error {
	s.ctx = ctx

	// unpack the storage module to use, if different from the default
	if s.Storage != nil {
		val, err := ctx.LoadModule(s, "Storage")
		if err != nil {
			return fmt.Errorf("loading TLS storage module: %s", err)
		}
		cmStorage, err := val.(caddy.StorageConverter).CertMagicStorage()
		if err != nil {
			return fmt.Errorf("creating TLS storage configuration: %v", err)
		}
		s.storage = cmStorage
	}

	// otherwise, use default storage
	if s.storage == nil {
		s.storage = ctx.Storage()
	}

	return nil
}

// Initialize sets the configuration for s and returns the starting keys.
func (s *Provider) Initialize(config *caddytls.SessionTicketService) ([][32]byte, error) {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Confirm the storage module is built in: caddy list-modules | grep caddy.storage
2. Fix the module name/options in the distributed STEK config
3. If you need a plugin storage backend, rebuild with xcaddy: xcaddy build --with github.com/caddyserver/...

// (shell) verify the storage module is compiled in before referencing it
caddy list-modules | grep '^caddy\.storage\.'

// For storage plugins: guarantee the converter interface at compile time
var _ caddy.StorageConverter = (*MyStorage)(nil)

if err := caddy.Run(cfg); err != nil {
	if strings.Contains(err.Error(), "loading TLS storage module") {
		// usually an unknown module name or failing plugin provisioning
		log.Printf("fix storage module config: %v", err)
	}
}

When it happens

Trigger: Configuring tls session ticket key encryption/distribution { storage <module> } in JSON where <module> is not a registered caddy storage module, or the storage module's own provisioning fails (bad options).

Common situations: Typos in the storage module name; referencing a Redis/S3/etc. storage plugin that is not compiled into the binary; storage module options that changed across versions.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• loading TLS storage module: %v
• creating TLS storage configuration: %v
• STEK gob corrupted: %v
• storing STEK gob: %v
• WebSocket connections aren't allowed.

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/1766ac192c1af043. Report an issue: GitHub.