What causes "failed to stat %v" in apache/beam?

Check permissions on every path component of dest so the process can traverse it (chmod +x on directories).

failed to stat

Error message

failed to stat %v

What it means

Returned by artifact.retrieve when os.Stat on the destination file fails with an error other than "not exist" (wrapf context: "failed to stat <filename>"). Before re-downloading, the library stats the target to decide whether to delete it; any stat failure other than IsNotExist aborts retrieval.

Solutions

Check permissions on every path component of dest so the process can traverse it (chmod +x on directories).
Remove conflicting entries where a file occupies a path that must be a directory.
Use a clean, dedicated artifact staging directory for each run to avoid stale/odd trees.
Inspect the wrapped error in the message to identify the exact failing path component.

Example fix

// before: nested, partially unwritable dest
artifact.Materialize(ctx, endpoint, deps, rt, "/srv/jobs/user/abc/artifacts")
// after: ensure dest exists and is traversable/writable
os.MkdirAll("/srv/jobs/user/abc/artifacts", 0o755)
artifact.Materialize(ctx, endpoint, deps, rt, "/srv/jobs/user/abc/artifacts")

Defensive patterns

Strategy: validation

Validate before calling

func canTraverse(dest string) error {
	for p := dest; p != "/" && p != "."; p = filepath.Dir(p) {
		if info, err := os.Stat(p); err != nil {
			return err
		} else if !info.IsDir() {
			return fmt.Errorf("%s is a file, not a directory", p)
		}
	}
	return nil
}
// call canTraverse(dest) before Materialize

Try / catch

if err := artifact.Materialize(ctx, endpoint, deps, rt, dest); err != nil {
	if strings.Contains(err.Error(), "failed to stat") {
		return fmt.Errorf("dest tree not traversable: %w", err)
	}
	return err
}

Prevention

Pre-create dest with os.MkdirAll(dest, 0o755) and ensure +x on all parent dirs.
Avoid stale trees where files occupy paths that should be directories.
Run workers under a user that owns or can traverse the artifact directory.
Use clean per-run directories to avoid odd symlink/permission residue.

When it happens

Trigger: os.Stat returning errors like EACCES (no search permission on a path component), ENOTDIR (a path component is a file), ELOOP (symlink loop), or device errors — anything that is not os.ErrNotExist.

Common situations: A parent directory in dest lacks execute permission for the running user; a previously retrieved artifact file shares a name with a required subdirectory (path component is a file); broken mount or dangling symlink setup inside the dest tree.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/538275217e1b52d7. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/artifact/materialize.go:223

	dep            *pipepb.ArtifactInformation
	expectedSha256 string
}

func (a artifact) retrieve(ctx context.Context, dest string) error {
	path, err := extractStagingToPath(a.dep)
	if err != nil {
		return err
	}

	filename := filepath.Join(dest, filepath.FromSlash(path))

	_, err = os.Stat(filename)
	if err == nil {
		if err = os.Remove(filename); err != nil {
			return errors.Errorf("failed to delete: %v (remove: %v)", filename, err)
		}
	} else if !os.IsNotExist(err) {
		return errors.Wrapf(err, "failed to stat %v", filename)
	}

	if err := os.MkdirAll(filepath.Dir(filename), os.ModePerm); err != nil {
		return err
	}

	stream, err := a.client.GetArtifact(ctx, &jobpb.GetArtifactRequest{Artifact: a.dep})
	if err != nil {
		return err
	}

	fd, err := os.OpenFile(filename, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0755)
	if err != nil {
		return err
	}
	w := bufio.NewWriter(fd)

	sha256Hash, err := writeChunks(stream, w)

View on GitHub (pinned to 12126d8942)