caddyserver/caddy · error

creating TLS storage configuration: %v

Error message

creating TLS storage configuration: %v

What it means

After loading the custom storage module for distributed STEKs, Provision calls CertMagicStorage() to obtain the certmagic.Storage implementation; failure is wrapped as 'creating TLS storage configuration'. The module loaded, but failed to produce a usable storage backend.

Source

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

	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) {
	// keep a reference to the config; we'll need it when rotating keys
	s.stekConfig = config

	dstek, err := s.getSTEK()

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the wrapped error after the colon — it contains the storage backend's own message
2. Fix the storage module's options (connection strings, credentials, addresses)
3. Verify backend reachability from the Caddy host (redis-cli ping, etc.) before restarting Caddy

// Pre-deploy: prove the storage backend answers before Caddy provisions it
// (shell, redis example) redis-cli -h <host> -a $REDIS_PASS ping

// Wrap Caddy startup so provision failures surface the backend cause
if err := caddy.Run(cfg); err != nil {
	if strings.Contains(err.Error(), "creating TLS storage configuration") {
		// the suffix after the colon carries the backend error (auth, network, options)
		log.Printf("storage backend rejected config: %v", err)
	}
}

When it happens

Trigger: A storage module whose CertMagicStorage() errors — e.g. invalid connection settings, missing credentials, or unsupported configuration for the storage backend.

Common situations: Redis storage plugin with unreachable host in config, wrong database index, or auth mismatch; environment variables for storage credentials missing at provision time.

Understand the failure class

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

Related errors

• loading TLS storage module: %v
• loading TLS storage module: %s
• 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/31069e4c6a4a1cf5. Report an issue: GitHub.