kataras/iris · error

FileServer: fs is nil. The fs parameter should point to a fi

Error message

FileServer: fs is nil. The fs parameter should point to a file system of physical system directory or to an embedded one

What it means

FileServer (used by Party.HandleDir) serves files from an http.FileSystem. It panics immediately if the fs parameter is nil because there is no file system to serve from. The parameter must point to a physical system directory or an embedded (go:embed) file system.

Source

Thrown at core/router/fs.go:167

	Attachments: Attachments{
		Enable: false,
		Limit:  0,
		Burst:  0,
	},
	AssetValidator: nil,
	SPA:            false,
}

// FileServer returns a Handler which serves files from a specific file system.
// The first parameter is the file system,
// if it's a `http.Dir` the files should be located near the executable program.
// The second parameter is the settings that the caller can use to customize the behavior.
//
// See `Party#HandleDir` too.
// Examples can be found at: https://github.com/kataras/iris/tree/main/_examples/file-server
func FileServer(fs http.FileSystem, options DirOptions) context.Handler {
	if fs == nil {
		panic("FileServer: fs is nil. The fs parameter should point to a file system of physical system directory or to an embedded one")
	}

	// Make sure index name starts with a slash.
	if options.IndexName != "" {
		options.IndexName = prefix(options.IndexName, "/")
	}

	// Make sure PushTarget's paths are in the proper form.
	for path, filenames := range options.PushTargets {
		for idx, filename := range filenames {
			filenames[idx] = filepath.ToSlash(filename)
		}
		options.PushTargets[path] = filenames
	}

	if !options.Attachments.Enable {
		// make sure rate limiting is not used when attachments are not.
		options.Attachments.Limit = 0

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Pass a valid http.FileSystem, e.g. http.Dir("./public") for a physical directory
2. For embedded assets use //go:embed and pass http.FS(embeddedFS) (or iris.PrefixEmbed FS helpers)
3. If the FS comes from a function, check it for nil before calling FileServer

Example fix

// before
var fs http.FileSystem
router.HandleDir("/static", fs) // panics: fs is nil
// after
fs := http.Dir("./public") // or http.FS(embeddedFS)
router.HandleDir("/static", fs)

func mustFS(fs http.FileSystem) http.FileSystem {
    if fs == nil {
        panic("FileServer: provide http.Dir(path) or http.FS(embedded)")
    }
    return fs
}

func isNilFS(fs http.FileSystem) bool {
    return fs == nil
}

func handleDirSafe(app *iris.Application, path string, fs http.FileSystem, opts router.DirOptions) {
    defer func() {
        if r := recover(); r != nil {
            log.Fatalf("HandleDir(%q) failed: %v", path, r)
        }
    }()
    if isNilFS(fs) {
        fs = http.Dir("./public")
    }
    app.HandleDir(path, fs, opts)
}

When it happens

Trigger: Calling router.FileServer(nil, options) or Party.HandleDir with a nil http.FileSystem — e.g. http.Dir("") misuse, an embedded FS variable that failed to bind, or a helper returning (http.FileSystem, error) whose error path was ignored.

Common situations: Passing the result of http.Dir with wrong path handling; using go:embed but assigning to the wrong variable so the FS is nil; wrapping http.FS(embedded) conversions incorrectly; conditional FS setup skipped in tests.

Related errors

• HandleDir: no directories found under the embedded file syst
• unexpected "fsOrDir" argument type of %T (string or http.Fil
• pool cannot be nil
• api container: set dependency matcher: fn cannot be nil
• toml: %w

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