caddyserver/caddy · error

creating TLS storage configuration: %v

Error message

creating TLS storage configuration: %v

What it means

The storage module loaded successfully but its CertMagicStorage() call (the caddy.StorageConverter interface) returned an error while constructing the underlying certmagic.Storage implementation. This is a failure inside the storage plugin itself — initializing a client, opening a database, checking a directory — not a module-loading problem.

Source

Thrown at modules/caddytls/automation.go:204

	for i, sub := range ap.SubjectsRaw {
		sub = repl.ReplaceAll(sub, "")
		subASCII, err := idna.ToASCII(sub)
		if err != nil {
			return fmt.Errorf("could not convert automation policy subject '%s' to punycode: %v", sub, err)
		}
		subjects[i] = subASCII
	}
	ap.subjects = subjects

	// policy-specific storage implementation
	if ap.StorageRaw != nil {
		val, err := tlsApp.ctx.LoadModule(ap, "StorageRaw")
		if err != nil {
			return fmt.Errorf("loading TLS storage module: %v", err)
		}
		cmStorage, err := val.(caddy.StorageConverter).CertMagicStorage()
		if err != nil {
			return fmt.Errorf("creating TLS storage configuration: %v", err)
		}
		ap.storage = cmStorage
	}

	// we don't store loaded modules directly in the certmagic config since
	// policy provisioning may happen more than once (during auto-HTTPS) and
	// loading a module clears its config bytes; thus, load the module and
	// store them on the policy before putting it on the config

	// load and provision any cert manager modules
	if ap.ManagersRaw != nil {
		ap.hadExplicitManagers = true
		vals, err := tlsApp.ctx.LoadModule(ap, "ManagersRaw")
		if err != nil {
			return fmt.Errorf("loading external certificate manager modules: %v", err)
		}
		for _, getCertVal := range vals.([]any) {
			ap.Managers = append(ap.Managers, getCertVal.(certmagic.Manager))

View on GitHub (pinned to 50e54ee279)

Solutions

1. Fix the underlying cause reported by the wrapped error (connectivity, credentials, or filesystem permissions).
2. For file_system storage, ensure the root directory exists and is writable by the Caddy service user (mkdir -p && chown).
3. For network backends, verify the endpoint is reachable from the Caddy host (telnet/curl) and credentials are current.
4. Start Caddy only after the storage backend dependency is up, or use a systemd dependency ordering.

Example fix

# before: root not writable
"storage": {"module": "file_system", "root": "/etc/caddy/storage"}

# after
sudo mkdir -p /var/lib/caddy/storage && sudo chown caddy:caddy /var/lib/caddy/storage
"storage": {"module": "file_system", "root": "/var/lib/caddy/storage"}

// For file_system storage: check writability up front.
info, err := os.Stat(storageRoot)
if err != nil || !info.IsDir() {
    return fmt.Errorf("storage root %s missing", storageRoot)
}
probe := filepath.Join(storageRoot, ".probe")
if err := os.WriteFile(probe, nil, 0o600); err != nil {
    return fmt.Errorf("storage root %s not writable: %v", storageRoot, err)
}

When it happens

Trigger: A StorageConverter module whose CertMagicStorage() fails: unable to reach Redis/Consul/S3 endpoints, invalid TLS certs for the storage backend, permission denied creating files under the storage root, bad DSN.

Common situations: Storage backend endpoint down or DNS not resolving at Caddy startup; file_system storage pointing at a root the caddy user cannot write; expired cloud credentials; firewall blocking the storage backend port.

Understand the failure class

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

Related errors

• storing ECH private key: %v
• problem calling http loader url: %v
• HTTP transport TLS handshake %ds timeout
• loading root key: %v
• loading trusted root CA's PEM file: %s: %v

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