gofiber/fiber · error · ErrUnknownTag

logtemplate: unknown tag

Error message

logtemplate: unknown tag

What it means

ErrUnknownTag ('logtemplate: unknown tag', internal/logtemplate/errors.go:12) is the sentinel behind *UnknownTagError, returned by logtemplate.Build (template.go:76,84) when a log format string references a ${tag} or ${tag:param} that has no registered renderer. The typed UnknownTagError carries the offending Tag, an optional Param, and a Hint (e.g. 'did you mean ${tag:param}?') so callers can report exactly which tag is unknown.

Source

Thrown at internal/logtemplate/errors.go:12

package logtemplate

import (
	"errors"
	"strconv"
)

// ErrUnknownTag indicates that the template references a tag that has no
// registered renderer. The format may be a bare ${tag} or a parametric
// ${tag:param}; in both cases the unmatched name is reported via
// UnknownTagError so callers can extract it programmatically.
var ErrUnknownTag = errors.New("logtemplate: unknown tag")

// UnknownTagError is the typed error returned when a template references an
// unknown tag. Tag is the offending tag including any parametric suffix
// (without the surrounding "${" / "}"). Param is the parameter portion when
// the tag was parametric, or the empty string for bare tags. Hint is an
// optional human-readable suggestion — currently set when a bare tag was
// referenced but a parametric base of the same name is registered.
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 + ")"
	}

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Register the tag before referencing it (e.g. log.RegisterContextTag or ensure the producing middleware's New() ran).
2. Use the exported tag constants (log.TagRequestID, etc.) instead of hand-typed names to avoid typos.
3. For parametric tags, include the trailing colon, e.g. ${value:userId}; read UnknownTagError.Hint for the suggested fix.

Example fix

// before
log.SetContextTemplate(log.ContextConfig{
    Format: "[${traceid}] ", // 'traceid' not registered
})

// after
log.SetContextTemplate(log.ContextConfig{
    Format: "[${" + log.TagRequestID + "}] ", // uses registered constant
})

// Pre-check that every tag in a format string is registered.
func checkTags(format string, registered map[string]bool) error {
    for _, m := range regexp.MustCompile(`\$\{([^}]+)}`).FindAllStringSubmatch(format, -1) {
        name := m[1]
        if i := strings.IndexByte(name, ':'); i >= 0 { name = name[:i+1] }
        if !registered[name] {
            return fmt.Errorf("format references unknown tag %q", m[1])
        }
    }
    return nil
}

// Narrow an error to the typed UnknownTagError to extract the tag name.
func unknownTag(err error) (tag string, ok bool) {
    var ute *logtemplate.UnknownTagError
    if errors.As(err, &ute) {
        return ute.Tag, true
    }
    return "", false
}

if err := log.SetContextTemplate(cfg); err != nil {
    var ute *logtemplate.UnknownTagError
    if errors.As(err, &ute) {
        log.Printf("unknown log tag %q (hint: %s)", ute.Tag, ute.Hint)
    }
    return err
}

When it happens

Trigger: Setting a logger/context format like "[${traceid}] " where 'traceid' was never registered, or using ${value:KEY} correctly but misspelling a custom tag. logtemplate.Build walks the format, and any ${...} whose inner name isn't in the tag-functions map yields this error. In the logger middleware, New(Config{Format: ...}) panics with the typed error; in log.SetContextTemplate it is returned.

Common situations: Referencing a middleware-produced tag (e.g. ${requestid}) before that middleware is initialized, typoing a tag name, or using a parametric tag without the trailing ':' (the hint catches this). Upgrading Fiber and using a tag renamed between versions also surfaces it.

Related errors

• log: context tag name and function are required
• log: context tag is reserved
• min constraint requires an argument
• max constraint requires an argument
• range constraint requires two arguments

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