hasura/graphql-engine · error · errors.Error

cannot validate directory '%s': [%s] not found

Error message

cannot validate directory '%s': [%s] not found

What it means

ValidateDirectory checks that every required entry (config.yaml, migrations/, optional metadata.yaml) exists inside dir. When one or more are missing, it returns this error listing the missing names. It is the definitive 'your project layout is incomplete' signal from both InitRun and the recursive validator.

Source

Thrown at cli/directory.go:136

	var op errors.Op = "cli.ValidateDirectory"

	notFound := []string{}

	for _, f := range filesRequired {
		if _, err := os.Stat(filepath.Join(dir, f)); stderrors.Is(err, fs.ErrNotExist) {
			relpath, e := filepath.Rel(dir, f)
			if e == nil {
				f = relpath
			}

			notFound = append(notFound, f)
		}
	}

	if len(notFound) > 0 {
		return errors.E(
			op,
			fmt.Errorf(
				"cannot validate directory '%s': [%s] not found",
				dir,
				strings.Join(notFound, ", "),
			),
		)
	}

	return nil
}

// CheckFilesystemBiundary returns an error if dir is filesystem root.
func CheckFilesystemBoundary(dir string) error {
	var op errors.Op = "cli.CheckFilesystemBoundary"
	// since filepath.Abs calls filepath.Clean the path is expected to be in "clean" state
	isWindowsRoot, _ := regexp.MatchString(`^[a-zA-Z]:\\$`, dir)
	// return error if filesystem boundary is hit
	if dir == "/" || isWindowsRoot {
		return errors.E(op, "filesystem boundary hit")

View on GitHub (pinned to 724551b9ae)

Solutions

1. Re-run the init command to regenerate the missing scaffolding
2. Create the missing entries listed in the error: touch config.yaml and mkdir migrations
3. Check for renames like config.yml vs config.yaml and correct the filename

Example fix

# before
# dir has only migrations/
mycli --dir ./proj run
# after
touch ./proj/config.yaml && mycli --dir ./proj run

required := []string{"config.yaml", "migrations"}
var missing []string
for _, r := range required {
    if _, err := os.Stat(filepath.Join(dir, r)); err != nil {
        missing = append(missing, r)
    }
}
if len(missing) > 0 {
    log.Fatalf("missing required entries: %s", strings.Join(missing, ", "))
}

if err := cli.ValidateDirectory(dir); err != nil {
    if strings.Contains(err.Error(), "not found") {
        // parse the bracketed list, create/scaffold those entries, retry
    }
}

When it happens

Trigger: Calling InitRun or recursivelyValidateDirectory on a directory that lacks config.yaml or the migrations/ folder; required files deleted, renamed, or never generated by init.

Common situations: Partial or interrupted 'init'; hand-created projects that skipped migrations/; renamed config.yaml (e.g. config.yml); fresh clone of a repo where required files are gitignored.

Related errors

• did not find required directory. use 'init'?: %w
• '%s' is not a directory: %w
• validating global config file failed: %w
• expected extension to be one of %v but got %s on file %s
• error while parsing the endpoint :%w

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