hasura/graphql-engine · error

cannot write metadata directory: %w

Error message

cannot write metadata directory: %w

What it means

os.MkdirAll failed for the metadata directory (<ExecutionDirectory>/metadata) during init of a config v2+ project. Created only when config.Version >= cli.V2.

Source

Thrown at cli/commands/init.go:304

	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)
		plugins = append(plugins, querycollections.New(o.EC, o.EC.MetadataDir))
		plugins = append(plugins, allowlist.New(o.EC, o.EC.MetadataDir))
		plugins = append(plugins, remoteschemas.New(o.EC, o.EC.MetadataDir))
		plugins = append(plugins, actions.New(o.EC, o.EC.MetadataDir))

		plugins = append(plugins, crontriggers.New(o.EC, o.EC.MetadataDir))
		if config.Version == cli.V3 {
			plugins = append(plugins, metadataVersion.New(o.EC, o.EC.MetadataDir))
			plugins = append(plugins, sources.New(o.EC, o.EC.MetadataDir))

View on GitHub (pinned to 724551b9ae)

Solutions

1. Ensure the project directory is writable and 'metadata' is not a regular file
2. Fix permissions/disk issues and re-run init
3. If not needing metadata directory, init with config version 1

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

When it happens

Trigger: Init with config version 2 or 3 where the metadata directory cannot be created (permissions/ENOTDIR/EROFS).

Common situations: v2/v3 project init on restricted filesystems; existing file named 'metadata' in the project dir; container read-only mounts.

Related errors

• error creating setup directories: %w
• cannot write migration directory: %w
• cannot create metadata files: %w
• cannot write seeds directory: %w
• unable to create directory: %w

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