{"id":"4c06b1fc05689bd7","repo":"gofiber/fiber","slug":"logtemplate-unknown-tag","errorCode":null,"errorMessage":"logtemplate: unknown tag","messagePattern":"logtemplate: unknown tag","errorType":"exception","errorClass":"ErrUnknownTag","httpStatus":null,"severity":"error","filePath":"internal/logtemplate/errors.go","lineNumber":12,"sourceCode":"package logtemplate\n\nimport (\n\t\"errors\"\n\t\"strconv\"\n)\n\n// ErrUnknownTag indicates that the template references a tag that has no\n// registered renderer. The format may be a bare ${tag} or a parametric\n// ${tag:param}; in both cases the unmatched name is reported via\n// UnknownTagError so callers can extract it programmatically.\nvar ErrUnknownTag = errors.New(\"logtemplate: unknown tag\")\n\n// UnknownTagError is the typed error returned when a template references an\n// unknown tag. Tag is the offending tag including any parametric suffix\n// (without the surrounding \"${\" / \"}\"). Param is the parameter portion when\n// the tag was parametric, or the empty string for bare tags. Hint is an\n// optional human-readable suggestion — currently set when a bare tag was\n// referenced but a parametric base of the same name is registered.\ntype UnknownTagError struct {\n\tTag   string\n\tParam string\n\tHint  string\n}\n\nfunc (e *UnknownTagError) Error() string {\n\tmsg := ErrUnknownTag.Error() + \": \" + strconv.Quote(e.Tag)\n\tif e.Hint != \"\" {\n\t\tmsg += \" (\" + e.Hint + \")\"\n\t}","sourceCodeStart":1,"sourceCodeEnd":30,"githubUrl":"https://github.com/gofiber/fiber/blob/9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c/internal/logtemplate/errors.go#L1-L30","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Register the tag before referencing it (e.g. log.RegisterContextTag or ensure the producing middleware's New() ran).","Use the exported tag constants (log.TagRequestID, etc.) instead of hand-typed names to avoid typos.","For parametric tags, include the trailing colon, e.g. ${value:userId}; read UnknownTagError.Hint for the suggested fix."],"exampleFix":"// before\nlog.SetContextTemplate(log.ContextConfig{\n    Format: \"[${traceid}] \", // 'traceid' not registered\n})\n\n// after\nlog.SetContextTemplate(log.ContextConfig{\n    Format: \"[${\" + log.TagRequestID + \"}] \", // uses registered constant\n})","handlingStrategy":"validation","validationCode":"// Pre-check that every tag in a format string is registered.\nfunc checkTags(format string, registered map[string]bool) error {\n    for _, m := range regexp.MustCompile(`\\$\\{([^}]+)}`).FindAllStringSubmatch(format, -1) {\n        name := m[1]\n        if i := strings.IndexByte(name, ':'); i >= 0 { name = name[:i+1] }\n        if !registered[name] {\n            return fmt.Errorf(\"format references unknown tag %q\", m[1])\n        }\n    }\n    return nil\n}","typeGuard":"// Narrow an error to the typed UnknownTagError to extract the tag name.\nfunc unknownTag(err error) (tag string, ok bool) {\n    var ute *logtemplate.UnknownTagError\n    if errors.As(err, &ute) {\n        return ute.Tag, true\n    }\n    return \"\", false\n}","tryCatchPattern":"if err := log.SetContextTemplate(cfg); err != nil {\n    var ute *logtemplate.UnknownTagError\n    if errors.As(err, &ute) {\n        log.Printf(\"unknown log tag %q (hint: %s)\", ute.Tag, ute.Hint)\n    }\n    return err\n}","preventionTips":["Register tags before referencing them in a format.","Use exported tag constants (log.TagRequestID, etc.) instead of typed names.","For parametric tags, include the trailing colon and read the Hint field."],"tags":["logging","template","config","fiber"],"analyzedSha":"9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c","analyzedAt":"2026-08-04T21:44:03.395Z","schemaVersion":2}