hasura/graphql-engine · error · errors.Error

did not find required directory. use 'init'?: %w

Error message

did not find required directory. use 'init'?: %w

What it means

validateDirectory stats the resolved execution directory and this error fires when os.Stat returns fs.ErrNotExist. It means the directory the CLI was told to operate on simply does not exist on disk, and the message hints the project may not have been scaffolded yet.

Source

Thrown at cli/directory.go:48

		if err != nil {
			return errors.E(op, fmt.Errorf("error getting current working directory: %w", err))
		}

		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

View on GitHub (pinned to 724551b9ae)

Solutions

1. Run the tool's init command to scaffold the project directory before validating
2. Double-check the path passed via the directory flag/config for typos or wrong relative base
3. If in a container, confirm the volume/workdir is mounted and the path matches

Example fix

# before
mycli --dir ./myproj run   # myproj does not exist
# after
mycli init && mycli --dir ./myproj run

if _, err := os.Stat(projectDir); stderrors.Is(err, fs.ErrNotExist) {
    log.Fatalf("project directory %s missing; run 'init' first", projectDir)
}

if err := ec.Validate(); err != nil {
    if strings.Contains(err.Error(), "did not find required directory") {
        // scaffold the project or fix the path, then retry
    }
}

When it happens

Trigger: Calling Validate with an ExecutionDirectory path that does not exist on the filesystem, e.g. a typo'd --dir flag, a project never created with the 'init' command, or a volume not mounted in a container.

Common situations: Forgetting to run the init command first; typos or stale relative paths in scripts/CI; Docker volume or Kubernetes PVC not mounted at the expected path; running from the wrong checkout.

Related errors

• '%s' is not a directory: %w
• metadata diff only works with folder but got file %s
• writing metadata to file: %w
• reading metadata file: %w
• error finding absolute path for project directory: %w

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