{"record":{"id":"1e5fd1ba1e6b2e56","repo":"caddyserver/caddy","slug":"loading-log-encoder-module-v","errorCode":null,"errorMessage":"loading log encoder module: %v","messagePattern":"loading log encoder module: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"logging.go","lineNumber":368,"sourceCode":"\tif cl.writerOpener == nil {\n\t\tcl.writerOpener = StderrWriter{}\n\t}\n\tvar err error\n\tcl.writer, _, err = logging.openWriter(cl.writerOpener)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"opening log writer using %#v: %v\", cl.writerOpener, err)\n\t}\n\n\t// set up the log level\n\tcl.levelEnabler, err = parseLevel(cl.Level)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif cl.EncoderRaw != nil {\n\t\tmod, err := ctx.LoadModule(cl, \"EncoderRaw\")\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"loading log encoder module: %v\", err)\n\t\t}\n\t\tcl.encoder = mod.(zapcore.Encoder)\n\n\t\t// if the encoder module needs the writer to determine\n\t\t// the correct default to use for a nested encoder, we\n\t\t// pass it down as a secondary provisioning step\n\t\tif cfd, ok := mod.(ConfiguresFormatterDefault); ok {\n\t\t\tif err := cfd.ConfigureDefaultFormat(cl.writerOpener); err != nil {\n\t\t\t\treturn fmt.Errorf(\"configuring default format for encoder module: %v\", err)\n\t\t\t}\n\t\t}\n\t}\n\tif cl.encoder == nil {\n\t\tcl.encoder = newDefaultProductionLogEncoder(cl.writerOpener)\n\t}\n\tcl.buildCore()\n\tif cl.CoreRaw != nil {\n\t\tmod, err := ctx.LoadModule(cl, \"CoreRaw\")","sourceCodeStart":350,"sourceCodeEnd":386,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/logging.go#L350-L386","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Fix the encoder module name (e.g. json, console, filter, append).","If using a third-party encoder, rebuild with xcaddy so the plugin is imported and registered.","Validate the remaining keys in the encoder object against that module's documented schema."],"exampleFix":"// before (caddyfile)\nlog {\n    encoder jsn {\n        time_format iso8601\n    }\n}\n\n// after\nlog {\n    encoder json {\n        time_format iso8601\n    }\n}","handlingStrategy":"validation","validationCode":"// before load: confirm the encoder module exists in this binary\nif _, err := caddy.GetModule(\"caddy.logging.encoders.json\"); err != nil {\n    return fmt.Errorf(\"encoder module missing from build: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := caddy.Validate(cfg); err != nil {\n    if strings.Contains(err.Error(), \"loading log encoder module\") {\n        // inspect nested cause: module-not-registered vs provisioning error\n    }\n    return err\n}","preventionTips":["Pin xcaddy plugin versions in CI so encoder modules are always present.","Use 'caddy list-modules' output as a checklist before referencing encoder names in config.","Prefer generating JSON via 'caddy adapt' rather than hand-writing encoder objects."],"tags":["logging","module-system","configuration"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}