hasura/graphql-engine · error · errors.Error

error getting directory details: %w

Error message

error getting directory details: %w

What it means

os.Stat on the execution directory returned an error other than not-exist (for example permission denied, or a path component that is a file). The CLI cannot inspect the directory's metadata, so validation aborts with this wrapped error.

Source

Thrown at cli/directory.go:51

		ec.ExecutionDirectory = cwd
	} else {
		ec.ExecutionDirectory, err = filepath.Abs(ec.ExecutionDirectory)
		if err != nil {
			return errors.E(
				op,
				fmt.Errorf("error finding absolute path for project directory: %w", err),
			)
		}
	}

	ed, err := os.Stat(ec.ExecutionDirectory)
	if err != nil {
		if stderrors.Is(err, fs.ErrNotExist) {
			return errors.E(op, fmt.Errorf("did not find required directory. use 'init'?: %w", err))
		}

		return errors.E(op, fmt.Errorf("error getting directory details: %w", err))
	}

	if !ed.IsDir() {
		return errors.E(op, fmt.Errorf("'%s' is not a directory: %w", ed.Name(), err))
	}
	// config.yaml
	// migrations/
	// (optional) metadata.yaml
	dir, err := recursivelyValidateDirectory(ec.ExecutionDirectory)
	if err != nil {
		return errors.E("validate: %w", err)
	}

	ec.ExecutionDirectory = dir

	return nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check permissions along the whole path: namei -l /path/to/dir and fix with chmod/chown
2. Inspect the wrapped error text to identify whether it is EACCES, EIO, or a symlink issue
3. Repair or remove broken symlinks in the path and retry

Example fix

# before
mycli --dir /srv/proj run   # EACCES
# after
sudo chown -R $USER:$USER /srv/proj && mycli --dir /srv/proj run

if _, err := os.Stat(projectDir); err != nil && !stderrors.Is(err, fs.ErrNotExist) {
    log.Fatalf("cannot inspect %s: %v (check permissions/mounts)", projectDir, err)
}

if err := ec.Validate(); err != nil {
    var pathErr *os.PathError
    if stderrors.As(err, &pathErr) {
        // inspect pathErr.Err for EACCES/EIO and remediate permissions or mounts
    }
}

When it happens

Trigger: Calling Validate when the process lacks search/execute permission on a path component leading to ExecutionDirectory, or when stat fails due to I/O errors, dangling symlinks in the path, or SELinux/AppArmor denials.

Common situations: Running the CLI as a different user than the directory owner; restricted mount points or NFS stale handles; symlink loops or broken symlinks inside the path; hardened container security contexts.

Understand the failure class

Background: Permission denied / not authorized / 403 Forbidden: access-control rejections when the caller lacks the required role, grant, or ownership — this error's family across 18 libraries.

Related errors

• error checking move target dir %q: %w
• writing metadata to file: %w
• write file: %w
• cannot create global config directory: %w
• write global config file: %w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/1133d0076eff2f9a. Report an issue: GitHub.