hasura/graphql-engine · error

cannot write metadata to project: %w

Error message

cannot write metadata to project: %w

What it means

After a successful server export in directory mode, writing the metadata files into the project via metadataHandler.WriteMetadata failed, and that failure is wrapped as 'cannot write metadata to project'. This is a local filesystem error class — the server interaction already succeeded.

Source

Thrown at cli/commands/metadata_handlers.go:50

}

type metadataModeDirectoryHandler struct{}

func (m *metadataModeDirectoryHandler) Export(o *MetadataExportOptions) error {
	var op errors.Op = "commands.metadataModeDirectoryHandler.Export"

	metadataHandler := projectmetadata.NewHandlerFromEC(o.EC)
	files, err := metadataHandler.ExportMetadata()

	o.EC.Spinner.Stop()

	if err != nil {
		return errors.E(op, fmt.Errorf("failed to export metadata: %w", err))
	}

	err = metadataHandler.WriteMetadata(files)
	if err != nil {
		return errors.E(op, fmt.Errorf("cannot write metadata to project: %w", err))
	}

	return nil
}

func (m *metadataModeDirectoryHandler) Apply(o *MetadataApplyOptions) error {
	var op errors.Op = "commands.metadataModeDirectoryHandler.Apply"

	metadataHandler := projectmetadata.NewHandlerFromEC(o.EC)
	if !o.DryRun {
		if o.EC.Config.Version == cli.V2 {
			_, err := metadataHandler.V1ApplyMetadata()
			if err != nil {
				return errors.E(op, errorApplyingMetadata(err))
			}

			o.EC.Logger.Debug("metadata applied using v1 replace_metadata")
		} else {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check write permissions on the project's metadata directory: chmod/adjust ownership as needed
2. Remove any regular file blocking creation of the metadata directory tree
3. Ensure the project volume is mounted read-write in containers
4. Free disk space if the wrapped error shows ENOSPC

Example fix

# before (file blocking the directory)
./metadata  # a regular file
# after
rm ./metadata && hasura metadata export

# Shell: verify writability and no file/dir conflicts
[ ! -f metadata ] || { echo "'metadata' is a file, not a dir"; exit 1; }
mkdir -p metadata && touch metadata/.probe && rm metadata/.probe

// Go
func canWriteMetadataDir(root string) bool {
  dir := filepath.Join(root, "metadata")
  if info, err := os.Stat(dir); err == nil && !info.IsDir() {
    return false
  }
  return os.MkdirAll(dir, 0o755) == nil
}

When it happens

Trigger: `hasura metadata export` where the metadata directory (or files/databases subdirectories) cannot be written: permission denied, read-only filesystem, path conflicts with an existing file where a directory is expected, or disk full.

Common situations: Running the CLI in Docker/CI without write permissions on the mounted project, a file named 'metadata' occupying the directory path, SELinux/AppArmor denials, or full disks.

Related errors

• failed to export metadata: %w
• writing metadata to file: %w
• error removing migrations from project: %w
• failed to create seed file: %w
• error getting directory details: %w

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