What causes "logger: unknown template tag" in gofiber/fiber?

Fix the typo: consult the tag constants in middleware/logger/tags.go for valid names.

logger: unknown template tag

Error message

logger: unknown template tag

What it means

Returned (wrapped in UnknownTagError) by middleware/logger.New when the configured Config.Format references a template tag with no registered renderer. The typed UnknownTagError carries Tag, Param, and a Hint; its Unwrap returns ErrUnknownTag so errors.Is works. Construction fails at New so a misconfigured logger never starts serving.

Solutions

Fix the typo: consult the tag constants in middleware/logger/tags.go for valid names.
Register the custom tag with logger.RegisterTag before calling logger.New, or pass it via Config.CustomTags.
If the error includes a Hint, follow it (e.g. a bare tag may need a ':param' suffix).
Use logger.MustRegisterTag only during init, not per-request.

Example fix

// before
logger.New(logger.Config{Format: "${stats}"}) // typo
// after
logger.New(logger.Config{Format: "${status}"})

Defensive patterns

Strategy: validation

Validate before calling

func validateFormat(format string, custom map[string]logger.LogFunc) error {
    // call logger.New in a recover, or maintain a set of valid tag names
    // from middleware/logger/tags.go and check Format references before starting.
    return nil
}

Try / catch

h, err := logger.New(cfg)
if err != nil {
    var ute *logger.UnknownTagError
    if errors.As(err, &ute) {
        // fix ute.Tag in cfg.Format, or register ute.Tag via RegisterTag/CustomTags
    }
    return err
}

Prevention

Cross-check tag names against the constants in middleware/logger/tags.go.
Register custom tags in init before logger.New.
Use Config.CustomTags for per-instance tags rather than mutating global state.

When it happens

Trigger: Calling logger.New with a Format string containing a ${tag} (or ${tag:param}) for a tag that is neither a built-in logger tag nor registered via logger.RegisterTag nor supplied in Config.CustomTags.

Common situations: Typo in a tag name (e.g. ${stats} instead of ${status}); referencing a tag from a newer/older version; using a parametric tag without the param suffix the renderer expects; copy-pasting a format from another app without registering its custom tags.

Related errors

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/4273c3cebcdbb438. Report an issue: GitHub.

Appendix: source

Thrown at middleware/logger/errors.go:12

package logger

import (
	"errors"
	"strconv"

	"github.com/gofiber/fiber/v3/internal/logtemplate"
)

// ErrUnknownTag indicates that the logger middleware was configured with a
// format that references a tag with no registered renderer.
var ErrUnknownTag = errors.New("logger: unknown template tag")

// UnknownTagError is the typed error panicked from New when Config.Format
// references an unknown tag. Tag is the offending tag including any
// parametric suffix; Param is the parameter portion when the tag was
// parametric (empty for bare tags); Hint, when non-empty, is a human-
// readable suggestion (e.g. parametric form for a likely-mistyped bare tag).
type UnknownTagError struct {
	Tag   string
	Param string
	Hint  string
}

func (e *UnknownTagError) Error() string {
	msg := ErrUnknownTag.Error() + ": " + strconv.Quote(e.Tag)
	if e.Hint != "" {
		msg += " (" + e.Hint + ")"
	}
	return msg

View on GitHub (pinned to a105acad6c)