caddyserver/caddy · error

loading template extensions: %v

Error message

loading template extensions: %v

What it means

Returned by the templates handler's Provision when loading custom template function modules (the 'extensions' field, module namespace http.handlers.templates.functions) fails. The wrapped error typically names the module and reason, such as unknown module or failed provisioning.

Source

Thrown at modules/caddyhttp/templates/templates.go:415

type CustomFunctions interface {
	// CustomTemplateFunctions should return the mapping from custom function names to implementations.
	CustomTemplateFunctions() template.FuncMap
}

// CaddyModule returns the Caddy module information.
func (Templates) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:  "http.handlers.templates",
		New: func() caddy.Module { return new(Templates) },
	}
}

// Provision provisions t.
func (t *Templates) Provision(ctx caddy.Context) error {
	t.logger = ctx.Logger()
	mods, err := ctx.LoadModule(t, "ExtensionsRaw")
	if err != nil {
		return fmt.Errorf("loading template extensions: %v", err)
	}
	for _, modIface := range mods.(map[string]any) {
		t.customFuncs = append(t.customFuncs, modIface.(CustomFunctions).CustomTemplateFunctions())
	}

	if t.MIMETypes == nil {
		t.MIMETypes = defaultMIMETypes
	}
	if t.FileRoot == "" {
		t.FileRoot = "{http.vars.root}"
	}
	return nil
}

// Validate ensures t has a valid configuration.
func (t *Templates) Validate() error {
	if len(t.Delimiters) != 0 && len(t.Delimiters) != 2 {
		return fmt.Errorf("delimiters must consist of exactly two elements: opening and closing")

View on GitHub (pinned to 50e54ee279)

Solutions

1. Check the wrapped error for the module name and reason
2. Build with the plugin: `xcaddy build --with <plugin-module-path>`
3. Verify the extension appears under http.handlers.templates.functions in `caddy list-modules`
4. Remove the extensions block if the functionality is not needed

Example fix

# before (binary lacks the plugin)
# in Caddyfile: templates { extensions frappe }

# after
xcaddy build --with github.com/benchkram/frp-go/caddyfrp
# then restart with the same config

caddy list-modules | grep 'http.handlers.templates.functions' || echo 'no template extensions compiled in'

When it happens

Trigger: A JSON/Caddyfile config for the templates handler that declares extensions (e.g. inline SVG, frappe, placeholders custom modules) not present in the binary, or whose own Provision fails.

Common situations: Using a third-party template extension plugin without building Caddy with xcaddy, a plugin version incompatible with the current Caddy core, or a typo in the extension module name in JSON config.

Related errors

• maybe %s: invalid number of return values: %d
• --input is required
• provisioning admin router module %s: %v
• encoding new config: %v
• loading new config: %v

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