io/fs: fs.Sub does not cause error if directory is not present

[Sebbito]

Go version

1.25.7

Output of go env in your module/workspace:

AR='ar'
CC='clang'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='clang++'
GCCGO='gccgo'
GO111MODULE=''
GOARCH='arm64'
GOARM64='v8.0'
GOAUTH='netrc'
GOBIN=''
GOCACHE='/Users/user/Library/Caches/go-build'
GOCACHEPROG=''
GODEBUG=''
GOENV='/Users/user/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/zr/wt9b1_rj0p371zpbgqfsczt40000gn/T/go-build2255838079=/tmp/go-build -gno-record-gcc-switches -fno-common'
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMOD='/Users/user/Code/website/website/go.mod'
GOMODCACHE='/Users/user/go/pkg/mod'
GONOPROXY='bitbucket.org/check24'
GONOSUMDB='bitbucket.org/check24'
GOOS='darwin'
GOPATH='/Users/user/go'
GOPRIVATE='bitbucket.org/check24'
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/Users/user/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.25.7.darwin-arm64'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTELEMETRYDIR='/Users/user/Library/Application Support/go/telemetry'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/Users/user/go/pkg/mod/golang.org/toolchain@v0.0.1-go1.25.7.darwin-arm64/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.25.7'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

Create a SubFS from an embed.FS for a directory that is not present. Then walk that directory and get an error:

package main

import (
	"embed"
	"io/fs"
	"log"
)

//go:embed content
var embedded embed.FS

func main() {
	s, err := fs.Sub(embedded, "test")
	if err != nil {
		log.Fatalf("error opening sub: %v", err)
	}
	err = fs.WalkDir(s, ".", func(path string, d fs.DirEntry, err error) error {
		if err != nil { return err }
		return nil
	})
	if err != nil {
		log.Fatalf("walkdir error: %v", err)
	}
}

What did you see happen?

Creating the SubFS worked which is misleading since the directory doesn't exist. Therefore the error will be thrown while walking the directory

$ tree
.
├── content
│   └── file
└── main.go

2 directories, 2 files

$ go run main.go 
2026/02/05 10:46:34 walkdir error: open .: file does not exist
exit status 1

What did you expect to see?

I would have expected fs.Sub to return an error and stop the execution before walking the directory:

$ go run main.go 
2026/02/05 10:46:34 error opening sub: 'test' does not exist
exit status 1

[gabyhelp]

Related Issues

• io/fs: should fs.Sub(fsys, "no such directory") return a file system that fails fstest.TestFS? #45087 (closed)
• io/fs: SubFS.Open returns incorrect errors for invalid paths #65419 (closed)
• io/fs: Sub should return a fs.FS that implements fs.SubFS #45349 (closed)
• io/fs: documentation of func Sub #44376 (closed)
• os: dirFS.ReadFile returns inconsistent PathError.Path #64366 (closed)
• io/fs: add func Sub(fsys FS, dir string) FS #42322 (closed)
• embed: FS.Open not compatible with os.Open #46626 (closed)

Related Code Changes

• io/fs: add Sub

Related Discussions

• Is embed.FS not expected to be walkable by fs.WalkDir()?

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[adonovan]

cc: @neild

[DanielMorsing]

Judging from the gaby output, this seems to be a recurring snag that people find. I think the design question here is whether there is a meaningful difference between an error and a fs.FS where every operation returns an error.

I can't see any problem with making fs.Sub check for the existence of . and returning an error, but user programs have continually surprised me in the past :)

[seankhliao]

right now Sub can be used to refer to a path that doesn't yet exist, but may be created in the future.

making it do an immediate check would break that

[Sebbito]

I think the design question here is whether there is a meaningful difference between an error and a fs.FS where every operation returns an error.

@DanielMorsing Yes that's more or less my question. I don't (or didn't) see a use case for having an fs.FS with those properties. If this is by-design which it seems it is, I don't really have a problem with that. My current solution is to fs.Stat(content, "test") and use the error value of that before creating a potentially invalid SubFS.

@seankhliao yes that is true. I'm skeptical that creating a SubFS and creating the directory it's accessing afterwards would be useful in practice though. Please correct me if I'm wrong: Creating a SubFS removes the ability for that SubFS to create the directory that it's trying to use. Thus you would have to check the existence of the directory the SubFS is trying to use either during creation or sometime after creation anyway.

I was just confused by this but I don't mind if this is just how SubFS just works :)

[mwriter]

Creating a SubFS removes the ability for that SubFS to create the directory that it's trying to use.

Look at it from the perspective of virtual file systems, for example testing/fstest/MapFS. When it can only be mock objects.
I fully support Sean's opinion on this issue.

[seankhliao]

The creation of the directory can be by something else, another goroutine, an external process, etc.

[mwriter]

The creation of the directory can be by something else, another goroutine, an external process, etc.

And it doesn't matter at all in this case. The main thing is that the file system should be a dynamic object. The same applies to any file paths in general. How many functions from the package path/filepath don't return any errors at all. In this case, it's appropriate to compare io/fs/Sub with path/filepath/Dir or path/filepath/Join.
Another thing is that there is also a strangeness for users: the presence of an error in the return value. Although this error is just the result of io/fs/Valid.
It's possible that a similar comment should be added for Sub, which is already available for Open:

// Open should reject attempts to open names that do not satisfy
// ValidPath(name), returning a *PathError with Err set to
// ErrInvalid or ErrNotExist.

[neild]

The io/fs.Sub documentation states:

[...] Sub returns a new FS implementation sub that, in effect, implements sub.Open(name) as fsys.Open(path.Join(dir, name)).

I don't see how we can make Sub return an error for a nonexistent directory without changing that documented behavior and breaking compatibility.

[gopherbot]

Change https://go.dev/cl/742284 mentions this issue: io/fs: document that Sub does not check for existence

[Sebbito]

Thanks for clearing this up!