caddyserver/caddy · error

loading log encoder module: %v

Error message

loading log encoder module: %v

What it means

Thrown when ctx.LoadModule fails to load the log encoder module referenced by the encoder field of a log config (EncoderRaw). LoadModule errors mean either the named module is not registered in this build, or the module's own JSON config failed to provision/validate.

Source

Thrown at logging.go:368

	if cl.writerOpener == nil {
		cl.writerOpener = StderrWriter{}
	}
	var err error
	cl.writer, _, err = logging.openWriter(cl.writerOpener)
	if err != nil {
		return fmt.Errorf("opening log writer using %#v: %v", cl.writerOpener, err)
	}

	// set up the log level
	cl.levelEnabler, err = parseLevel(cl.Level)
	if err != nil {
		return err
	}

	if cl.EncoderRaw != nil {
		mod, err := ctx.LoadModule(cl, "EncoderRaw")
		if err != nil {
			return fmt.Errorf("loading log encoder module: %v", err)
		}
		cl.encoder = mod.(zapcore.Encoder)

		// if the encoder module needs the writer to determine
		// the correct default to use for a nested encoder, we
		// pass it down as a secondary provisioning step
		if cfd, ok := mod.(ConfiguresFormatterDefault); ok {
			if err := cfd.ConfigureDefaultFormat(cl.writerOpener); err != nil {
				return fmt.Errorf("configuring default format for encoder module: %v", err)
			}
		}
	}
	if cl.encoder == nil {
		cl.encoder = newDefaultProductionLogEncoder(cl.writerOpener)
	}
	cl.buildCore()
	if cl.CoreRaw != nil {
		mod, err := ctx.LoadModule(cl, "CoreRaw")

View on GitHub (pinned to 50e54ee279)

Solutions

1. Check the wrapped error: 'module not registered' means the module ID is wrong or not compiled in; anything else comes from the encoder's provisioning.
2. Fix the encoder module name (e.g. json, console, filter, append).
3. If using a third-party encoder, rebuild with xcaddy so the plugin is imported and registered.
4. Validate the remaining keys in the encoder object against that module's documented schema.

Example fix

// before (caddyfile)
log {
    encoder jsn {
        time_format iso8601
    }
}

// after
log {
    encoder json {
        time_format iso8601
    }
}

// before load: confirm the encoder module exists in this binary
if _, err := caddy.GetModule("caddy.logging.encoders.json"); err != nil {
    return fmt.Errorf("encoder module missing from build: %w", err)
}

if err := caddy.Validate(cfg); err != nil {
    if strings.Contains(err.Error(), "loading log encoder module") {
        // inspect nested cause: module-not-registered vs provisioning error
    }
    return err
}

When it happens

Trigger: A logs block with encoder { format <name> ... } where <name> is not a registered zap encoder module, or where the encoder's inline arguments are invalid (unknown keys, bad values) causing Provision/Validate to fail.

Common situations: Custom builds (xcaddy) that omit the standard encoder modules; typos in the format name; JSON configs hand-edited with an encoder object missing the name key; version changes that renamed or removed an encoder module.

Related errors

• invalid action type
• configuring default format for encoder module: %v
• loading log core module: %v
• include and exclude must not intersect, but found %s in both
• unrecognized log level: %s

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