gofiber/fiber · error · ErrUnknownTag

logger: unknown template tag

Error message

logger: unknown template tag

What it means

Returned/panicked by the logger middleware (errors.go:12) when Config.Format contains a placeholder tag that has no registered renderer. The middleware parses the format string at construction time (New) and builds a compiled template; an unknown tag produces an UnknownTagError (a typed error wrapping ErrUnknownTag) that is either returned from New or panicked, depending on how the logger is initialized. The error includes the offending tag name and an optional Hint.

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 9a4c7e57fe)

Solutions

1. Check the error's Tag field for the exact misspelled tag and correct it to a known tag (see the Tag* constants in logger/tags.go).
2. Register custom tags with logger.RegisterTag(name, fn) before calling logger.New().
3. Start with the default format and add tags incrementally to isolate the bad one.

Example fix

// before
app.Use(logger.New(logger.Config{
  Format: "${time} ${method} ${path} ${responesTime}\n", // typo
}))
// after
app.Use(logger.New(logger.Config{
  Format: "${time} ${method} ${path} ${latency}\n",
}))

// Before deploying, check all tags in your format string are known
knownTags := map[string]bool{"time":true,"method":true,"path":true,"status":true,"latency":true,"ip":true}
// parse ${...} tokens from your format and verify each is in knownTags or registered

When it happens

Trigger: Configuring logger.Config.Format with a typo or unsupported tag, e.g. '${responesTime}' instead of '${latency}', or referencing a custom tag that was never registered via RegisterTag. The error surfaces at middleware construction (startup), not at request time.

Common situations: Typo in a tag name in the format string; referencing a tag from a newer/older version; forgetting to call RegisterTag for a custom tag before creating the logger; copy-pasting a format from documentation for a different version.

Related errors

• decode SHA256 password: invalid length
• logger: tag name and function are required
• remote address cannot be empty
• cache: insufficient space and no entries to evict
• csrf: referer does not match host or trusted origins

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/4273c3cebcdbb438.json. Report an issue: GitHub.