{"record":{"id":"e09243a3474575d0","repo":"kataras/iris","slug":"handledir-no-directories-found-under-the-embedded","errorCode":null,"errorMessage":"HandleDir: no directories found under the embedded file system","messagePattern":"HandleDir: no directories found under the embedded file system","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"context/fs.go","lineNumber":118,"sourceCode":"//\n// It affects the Application's API Builder's `HandleDir` method.\n//\n// This package-level variable can be modified on initialization.\nvar ResolveHTTPFS = func(fsOrDir any) http.FileSystem {\n\tvar fileSystem http.FileSystem\n\tswitch v := fsOrDir.(type) {\n\tcase string:\n\t\tfileSystem = http.Dir(v)\n\tcase http.FileSystem:\n\t\tfileSystem = v\n\tcase embed.FS:\n\t\tdireEtries, err := v.ReadDir(\".\")\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\n\t\tif len(direEtries) == 0 {\n\t\t\tpanic(\"HandleDir: no directories found under the embedded file system\")\n\t\t}\n\n\t\tsubfs, err := fs.Sub(v, direEtries[0].Name())\n\t\tif err != nil {\n\t\t\tpanic(err)\n\t\t}\n\t\tfileSystem = http.FS(subfs)\n\tcase fs.FS:\n\t\tfileSystem = http.FS(v)\n\tdefault:\n\t\tpanic(fmt.Sprintf(`unexpected \"fsOrDir\" argument type of %T (string or http.FileSystem or embed.FS or fs.FS)`, v))\n\t}\n\n\treturn fileSystem\n}\n\n// FindNames accepts a \"http.FileSystem\" and a root name and returns\n// the list containing its file names.","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/kataras/iris/blob/7bedaf55a0b64bbb2248a5845a2c60d81a30996a/context/fs.go#L100-L136","documentation":"When HandleDir (via its internal file system resolution) is given an embed.FS, Iris reads the root directory of the embedded FS and, if it is empty (no directories/files embedded), panics because it cannot locate a sub-filesystem to serve. This catches the common mistake of embedding with patterns that match nothing.","triggerScenarios":"Passing an embed.FS to HandleDir (or the fs-resolution helper) where //go:embed matched zero entries, so ReadDir(\".\") on the embedded FS returns an empty list.","commonSituations":"//go:embed directive pointing at a path that doesn't exist at build time, embed pattern excluded by .gitignore-like rules, embedding an empty placeholder directory without files.","solutions":["Fix the //go:embed pattern so it actually includes the directory's files (e.g. //go:embed public/* and rebuild).","Verify the embedded variable references the correct directory and that the build embeds files (check go build output).","Alternatively pass the embedded sub-directory via embed.FS with fs.Sub semantics handled by the library, or serve an os directory instead."],"exampleFix":"// before\n//go:embed public\nvar assetsFS embed.FS // pattern matched nothing -> empty FS\n// after\n//go:embed public/*\nvar assetsFS embed.FS\napp.HandleDir(\"/\", assetsFS)","handlingStrategy":"validation","validationCode":"entries, err := assetsFS.ReadDir(\".\")\nif err != nil || len(entries) == 0 {\n  log.Fatal(\"embedded FS is empty; check //go:embed pattern\")\n}\napp.HandleDir(\"/\", assetsFS)","typeGuard":"func embeddedFSEmpty(v embed.FS) bool {\n  entries, err := v.ReadDir(\".\")\n  return err != nil || len(entries) == 0\n}","tryCatchPattern":null,"preventionTips":["Verify //go:embed patterns include files (directories must contain matched files to embed)","Add a startup check that the embedded FS is non-empty","Rebuild after changing embedded assets — go:embed is compile-time"],"tags":["go","panic","embed","static-files"],"backgroundTag":"empty-embedded-filesystem","analyzedSha":"7bedaf55a0b64bbb2248a5845a2c60d81a30996a","analyzedAt":"2026-08-30T20:38:16.250Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}