hasura/graphql-engine · error

creating metadata file %s failed: %w

Error message

creating metadata file %s failed: %w

What it means

Raised by source/file's WriteMetadata when it cannot write a metadata file under the migrations filesystem (afero.Fs). It wraps the underlying filesystem error with the target path, so the cause is almost always permissions, a read-only FS, or an invalid path.

Source

Thrown at cli/migrate/source/file/file.go:352

	)
}

func (f *File) ReadName(version uint64) (name string) {
	return f.Migrations.ReadName(version)
}

func (f *File) WriteMetadata(files map[string][]byte) error {
	var op errors.Op = "file.File.WriteMetadata"

	for name, content := range files {
		fs := afero.NewOsFs()
		if err := fs.MkdirAll(filepath.Dir(name), os.ModePerm); err != nil {
			return errors.E(op, err)
		}

		err := afero.WriteFile(fs, name, content, 0o644)
		if err != nil {
			return errors.E(op, fmt.Errorf("creating metadata file %s failed: %w", name, err))
		}
	}

	return nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check permissions on the migrations directory and its parents; chmod/chown so the running user can write
2. If using a custom afero.Fs, ensure it supports WriteFile (use OsFs or a writable memfs)
3. Verify the disk isn't full or the path read-only (mount -o ro)
4. Run the operation from the project root so relative paths resolve correctly

Example fix

# before
$ docker run -v project:/hasura:ro hasura/graphql-engine-cli... # creating metadata file ... failed: permission denied

# after
$ docker run -v project:/hasura hasura/graphql-engine-cli... # mount writable

// Ensure target is writable before exporting
info, err := fs.Stat(migrationsDir)
if err == nil && info.IsDir() {
    probe := filepath.Join(migrationsDir, ".writeprobe")
    if err := afero.WriteFile(fs, probe, []byte{}, 0o644); err != nil {
        return fmt.Errorf("migrations dir not writable: %w", err)
    }
    _ = fs.Remove(probe)
}

if err := fileDrv.WriteMetadata(...); err != nil {
    if strings.Contains(err.Error(), "creating metadata file") {
        // filesystem/permission issue: check mount and permissions
    }
}

When it happens

Trigger: Calling file driver WriteMetadata (during metadata export or migration operations that persist files) when the migrations directory or its parent is not writable, the afero filesystem is read-only (e.g. embedded/embedfs), or the path doesn't exist and MkdirAll was skipped/failed.

Common situations: Running the CLI in a container or CI where /hasura or the project dir is mounted read-only; using an afero MemMapFs or embed FS in tests without write support; file ownership mismatch (running as non-root against a root-owned directory).

Related errors

• writing metadata to file: %w
• error removing migrations from project: %w
• failed to create seed file: %w
• creating metadata file %s failed: %w
• Error in model permission for model '{model_name}'{}: {error

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