kataras/iris · error

invalid root name

Error message

invalid root name

What it means

FindNames validates the root name/path before opening it inside the given http.FileSystem and rejects any name containing "..", which could traverse outside the root. It returns this error to prevent path traversal attacks when enumerating files.

Source

Thrown at context/fs.go:139

		subfs, err := fs.Sub(v, direEtries[0].Name())
		if err != nil {
			panic(err)
		}
		fileSystem = http.FS(subfs)
	case fs.FS:
		fileSystem = http.FS(v)
	default:
		panic(fmt.Sprintf(`unexpected "fsOrDir" argument type of %T (string or http.FileSystem or embed.FS or fs.FS)`, v))
	}

	return fileSystem
}

// FindNames accepts a "http.FileSystem" and a root name and returns
// the list containing its file names.
func FindNames(fileSystem http.FileSystem, name string) ([]string, error) {
	if strings.Contains(name, "..") {
		return nil, fmt.Errorf("invalid root name")
	}

	f, err := fileSystem.Open(name) // it's the root dir.
	if err != nil {
		return nil, err
	}
	defer f.Close()

	fi, err := f.Stat()
	if err != nil {
		return nil, err
	}

	if !fi.IsDir() {
		return []string{name}, nil
	}

	fileinfos, err := f.Readdir(-1)

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Remove ".." from the name: pass a clean, absolute-inside-root path (e.g. "assets/css"), or use filepath.Clean and re-check the result.
2. Never derive the root name from raw user input; whitelist allowed root names.
3. Use fs.Sub on an fs.FS to isolate a subtree instead of navigating with "..".

Example fix

// before
names, _ := context.FindNames(assetsFS, "../embeddings/files")
// after
names, _ := context.FindNames(assetsFS, "embeddings/files") // no ".." segments

if strings.Contains(name, "..") {
    return errors.New("invalid root name: path traversal not allowed")
}

names, err := context.FindNames(fs, name)
if err != nil {
    if strings.Contains(name, "..") {
        http.Error(w, "invalid path", http.StatusBadRequest)
    }
    return
}

When it happens

Trigger: Calling iris/context FindNames(fileSystem, name) where the name string contains "..", e.g. "../static" or "assets/../conf".

Common situations: Building the root name from user input or URL parameters; concatenating a config value with a relative prefix; assuming FindNames cleans paths like http.FileServer does (it does not).

Related errors

• auth: configuration: cookie block and cookie hash are requir
• empty form
• errors joined from param parser: strings.Join(p.errors, "\n"
• parameter is not alphabetical
• parameter is not a file

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/2362c9b9d33a5e80. Report an issue: GitHub.