caddyserver/caddy · error

parsing browse template: %v

Error message

parsing browse template: %v

What it means

Runtime (per-request) error from the file server's browse handler: makeBrowseTemplate failed to parse the template (custom file or built-in default). The wrapped error contains the Go template parse details.

Source

Thrown at modules/caddyhttp/fileserver/browse.go:203

	default:
		var fs http.FileSystem
		if fsrv.Root != "" {
			fs = http.Dir(repl.ReplaceAll(fsrv.Root, "."))
		}

		tplCtx := &templateContext{
			TemplateContext: templates.TemplateContext{
				Root:       fs,
				Req:        r,
				RespHeader: templates.WrappedHeader{Header: w.Header()},
			},
			browseTemplateContext: listing,
		}

		tpl, err := fsrv.makeBrowseTemplate(tplCtx)
		if err != nil {
			return fmt.Errorf("parsing browse template: %v", err)
		}
		if err := tpl.Execute(buf, tplCtx); err != nil {
			return caddyhttp.Error(http.StatusInternalServerError, err)
		}
		w.Header().Set("Content-Type", "text/html; charset=utf-8")
	}

	_, _ = buf.WriteTo(w)

	return nil
}

func (fsrv *FileServer) loadDirectoryContents(ctx context.Context, fileSystem fs.FS, dir fs.ReadDirFile, root, urlPath string, repl *caddy.Replacer) (*browseTemplateContext, error) {
	// modTime for the directory itself
	stat, err := dir.Stat()
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the wrapped error for line/column of the template syntax problem
2. Test the template with `go template` parsing locally (text/template Parse) before deploying
3. Remove TemplateFile to fall back to the built-in default template

Example fix

# before
{{.Listing.Name 
# after (well-formed)
{{.Name}}

// offline: parse the custom template before deploying
if _, err := template.New("t").ParseFiles("browse.html"); err != nil { log.Fatal(err) }

When it happens

Trigger: A request for a browsed directory with browse enabled while the template (custom TemplateFile or embedded BrowseTemplate) has invalid Go template syntax; parsing happens lazily per request here.

Common situations: Custom browse_template_file with malformed {{.Bad}} actions or unbalanced delimiters; a template using functions not in the template context.

Related errors

• parsing browse template file: %v
• parsing default browse template: %v
• the first option must be one of the following: %s, %s, %s, %
• the second option must be one of the following: %s, %s, but
• only max 2 sort options are allowed, but got %d

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