hasura/graphql-engine · error

cannot write migration directory: %w

Error message

cannot write migration directory: %w

What it means

os.MkdirAll failed for the migrations directory (<ExecutionDirectory>/migrations) during `hasura init`. Every init creates this directory regardless of config version.

Source

Thrown at cli/commands/init.go:295

	if o.AdminSecret != "" {
		config.AdminSecret = o.AdminSecret
	}

	// write the config file
	o.EC.Config = config
	o.EC.ConfigFile = filepath.Join(o.EC.ExecutionDirectory, "config.yaml")

	err = o.EC.WriteConfig(nil)
	if err != nil {
		return errors.E(op, fmt.Errorf("cannot write config file: %w", err))
	}

	// create migrations directory
	o.EC.MigrationDir = filepath.Join(o.EC.ExecutionDirectory, cli.DefaultMigrationsDirectory)

	err = os.MkdirAll(o.EC.MigrationDir, os.ModePerm)
	if err != nil {
		return errors.E(op, fmt.Errorf("cannot write migration directory: %w", err))
	}

	if config.Version >= cli.V2 {
		// create metadata directory
		o.EC.MetadataDir = filepath.Join(o.EC.ExecutionDirectory, cli.DefaultMetadataDirectory)

		err = os.MkdirAll(o.EC.MetadataDir, os.ModePerm)
		if err != nil {
			return errors.E(op, fmt.Errorf("cannot write metadata directory: %w", err))
		}

		err = o.EC.Version.GetServerFeatureFlags()
		if err != nil {
			o.EC.Logger.Warnf("error determining server feature flags: %v", err)
		}

		// create metadata files
		plugins := make(metadataobject.Objects, 0)

View on GitHub (pinned to 724551b9ae)

Solutions

1. Verify writability of the project dir and that no file named 'migrations' exists
2. Free space / fix mount options
3. Re-run init in a clean directory

if fi, err := os.Lstat(filepath.Join(dir, "migrations")); err == nil && !fi.IsDir() {
    log.Fatal("'migrations' exists but is not a directory")
}

When it happens

Trigger: Migrations directory cannot be created: permissions, ENOTDIR on a path component, or read-only filesystem.

Common situations: Same as other init mkdir failures: restricted containers, quota, path collisions with files named 'migrations'.

Related errors

• error creating setup directories: %w
• cannot write metadata directory: %w
• cannot write seeds directory: %w
• applying migrations on source: %s: %w
• operation failed: %w

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