caddyserver/caddy · error

loading storage module: %v

Error message

loading storage module: %v

What it means

While preparing a new config, run() loads the storage module declared in the top-level "storage" field via ctx.LoadModule(newCfg, "StorageRaw"). If the module cannot be loaded — unknown module name or failed provisioning — the error is wrapped as 'loading storage module'. Storage affects where certificates and state persist, so a failure here aborts the load.

Source

Thrown at caddy.go:544

	}
	err = newCfg.Logging.openLogs(ctx)
	if err != nil {
		return ctx, err
	}

	// create the new filesystem map
	newCfg.fileSystems = &filesystems.FileSystemMap{}

	// prepare the new config for use
	newCfg.apps = make(map[string]App)
	newCfg.failedApps = make(map[string]error)

	// set up global storage and make it CertMagic's default storage, too
	err = func() error {
		if newCfg.StorageRaw != nil {
			val, err := ctx.LoadModule(newCfg, "StorageRaw")
			if err != nil {
				return fmt.Errorf("loading storage module: %v", err)
			}
			stor, err := val.(StorageConverter).CertMagicStorage()
			if err != nil {
				return fmt.Errorf("creating storage value: %v", err)
			}
			newCfg.storage = stor
		}

		if newCfg.storage == nil {
			newCfg.storage = DefaultStorage
		}
		certmagic.Default.Storage = newCfg.storage

		return nil
	}()
	if err != nil {
		return ctx, err
	}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Check the wrapped error for the module ID and provisioning detail.
2. Verify the plugin is present: caddy list-modules | grep -i storage; rebuild with xcaddy build --with <plugin> if missing.
3. Fix the module's parameters (endpoint URL, credentials, bucket) per its docs.
4. Temporarily remove the storage block to fall back to DefaultStorage and isolate the issue.

Example fix

// before
"storage": { "module": "redis", "adress": "localhost:6379" }  // typo'd field

// after
"storage": { "module": "redis", "address": "localhost:6379" }

modName := cfg.StorageRaw["module"].(string) // after JSON decode
found := false
for _, m := range caddy.DefaultModules { // or 'caddy list-modules' out-of-band
    if m.ID.String() == "caddy.storage."+modName { found = true }
}
if !found { return fmt.Errorf("storage module %q not in build", modName) }

func isRegisteredStorage(mod caddy.Module) bool {
    _, ok := mod.(caddy.StorageConverter)
    return ok
}

When it happens

Trigger: JSON config with "storage": {"module": "some_module", ...} where the module is not compiled into the binary or its Provision() fails (bad connection params, unsupported scheme). Triggered on caddy run and on every admin config load with that storage block.

Common situations: Custom builds missing a storage plugin that the config references; Redis/PostgreSQL/S3 storage plugins with invalid endpoints or credentials; version upgrades renaming storage module fields; typo in the module key.

Related errors

• --input is required
• loading new config: %v
• creating storage value: %v
• server %s: %v
• loading listener wrapper modules: %v

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