unexpected "fsOrDir" argument type of %T (string or http.Fil

Error message

unexpected "fsOrDir" argument type of %T (string or http.FileSystem or embed.FS or fs.FS)

What it means

Iris's file-system resolver accepts a string path, http.FileSystem, embed.FS, or fs.FS as the HandleDir argument. When the value passed is none of these supported types, it panics with a message showing the offending Go type via %T.

Source

Thrown at context/fs.go:129

	case embed.FS:
		direEtries, err := v.ReadDir(".")
		if err != nil {
			panic(err)
		}

		if len(direEtries) == 0 {
			panic("HandleDir: no directories found under the embedded file system")
		}

		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()

View on GitHub (pinned to 7bedaf55a0)

Solutions

Convert the argument to a supported type: a directory path string, http.FileSystem (e.g. http.FS(v)), embed.FS, or fs.FS.
If using a custom filesystem, implement fs.FS so it is accepted via http.FS conversion.
Read the %T in the panic message to find exactly what type leaked in and fix the call site.

Example fix

// before
app.HandleDir("/static", myBytes) // []byte unsupported
// after
app.HandleDir("/static", http.FS(assetsFS)) // embed.FS converted to http.FileSystem

Defensive patterns

Strategy: type-guard

Validate before calling

switch v := arg.(type) {
case string, http.FileSystem, embed.FS, fs.FS:
  app.HandleDir("/static", v)
default:
  log.Fatalf("unsupported fsOrDir type %T", arg)
}

Type guard

func isSupportedFS(v any) bool {
  switch v.(type) {
  case string, http.FileSystem, embed.FS, fs.FS:
    return true
  default:
    return false
  }
}

Prevention

Pass only string paths, http.FileSystem, embed.FS, or fs.FS to HandleDir
Wrap custom filesystems with http.FS or implement fs.FS
Check the Iris version's documented HandleDir signature when upgrading

When it happens

Trigger: Passing any value other than string/http.FileSystem/embed.FS/fs.FS as the fsOrDir argument to HandleDir — e.g. a *bytes.Reader, a custom FS interface, or a typed nil of an unsupported type.

Common situations: Wrapping assets in a custom filesystem type not implementing fs.FS, passing a byte slice of files, or upgrading Iris where the supported argument set changed and old call sites use obsolete types.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

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