static middleware failed to read directory for listing: %w

Error message

static middleware failed to read directory for listing: %w

What it means

Returned by listDir() (static.go:328) when fs.ReadDir(filesystem, pathInFs) fails while generating a directory listing. This runs at request time when directory listing is enabled (ShowDirectory true) and the requested path resolves to a directory. The wrapped error is the underlying fs.ReadDir failure.

Source

Thrown at middleware/static.go:328

			return serveFile(c, file, info)
		}
	}, nil
}

func serveFile(c *echo.Context, file fs.File, info os.FileInfo) error {
	ff, ok := file.(io.ReadSeeker)
	if !ok {
		return errors.New("file does not implement io.ReadSeeker")
	}
	http.ServeContent(c.Response(), c.Request(), info.Name(), info.ModTime(), ff)
	return nil
}

func listDir(t *template.Template, pathInFs string, filesystem fs.FS, res http.ResponseWriter) error {
	files, err := fs.ReadDir(filesystem, pathInFs)
	if err != nil {
		return fmt.Errorf("static middleware failed to read directory for listing: %w", err)
	}

	// Create directory index
	res.Header().Set(echo.HeaderContentType, echo.MIMETextHTMLCharsetUTF8)
	data := struct {
		Name  string
		Files []any
	}{
		Name: pathInFs,
	}

	for _, f := range files {
		var size int64
		if !f.IsDir() {
			info, err := f.Info()
			if err != nil {
				return fmt.Errorf("static middleware failed to get file info for listing: %w", err)
			}

View on GitHub (pinned to 05489dc173)

Solutions

Check filesystem permissions on the served directory (read+execute for the process user).
Avoid broken or cyclic symlinks inside the served tree when using the OS filesystem.
Disable directory listing (StaticConfig.ShowList = false) if enumeration is not required.
If using embed.FS, ensure the directory was actually embedded (rebuild after adding files).

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the directory is readable before enabling listing.
func dirReadable(fsys fs.FS, dir string) error {
    _, err := fs.ReadDir(fsys, dir)
    return err
}

Prevention

Set directory permissions to allow the process user to read+execute.
Disable ShowDirectory listing on directories you don't need to enumerate.
Avoid serving from directories with broken or cyclic symlinks.

When it happens

Trigger: A request hits the static handler with directory listing enabled; the resolved path is a directory, but fs.ReadDir cannot enumerate it (permissions, broken symlink, or the directory was removed between Open and ReadDir).

Common situations: Filesystem permissions deny read on the directory; a symlink loop; using a custom fs.FS whose ReadDir is buggy; containerized deployments where the assets dir has restrictive perms.

Related errors

AI-assisted analysis of labstack/echo@05489dc173 (2026-08-04). Data as JSON: /data/errors/43547d71dfb0d0bf.json. Report an issue: GitHub.