hasura/graphql-engine · error

writing metadata to file: %w

Error message

writing metadata to file: %w

What it means

The final step of `metadata export` writes the (possibly YAML-converted) metadata bytes to the configured metadata file (o.EC.MetadataFile) with os.WriteFile using os.ModePerm. This error means the local file write failed — the directory does not exist, permissions are insufficient, or the path points somewhere invalid.

Source

Thrown at cli/commands/metadata_handlers.go:339

	}

	var metadataBytes []byte

	metadataBytes, err = io.ReadAll(metadata)
	if err != nil {
		return errors.E(op, fmt.Errorf("reading metadata from response: %w", err))
	}

	if mode == cli.MetadataModeYAML {
		metadataBytes, err = metadatautil.JSONToYAML(metadataBytes)
		if err != nil {
			return errors.E(op, fmt.Errorf("parsing metadata to yaml: %w", err))
		}
	}

	err = os.WriteFile(o.EC.MetadataFile, metadataBytes, os.ModePerm)
	if err != nil {
		return errors.E(op, fmt.Errorf("writing metadata to file: %w", err))
	}

	return nil
}

func apply(o *MetadataApplyOptions, mode cli.MetadataMode) error {
	var (
		op                 errors.Op = "commands.apply"
		localMetadataBytes []byte
		err                error
	)

	localMetadataBytes, err = os.ReadFile(o.EC.MetadataFile)
	if err != nil {
		return errors.E(op, fmt.Errorf("reading metadata file: %w", err))
	}

	if o.DryRun {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Create the parent directory for the configured metadata file path (e.g. mkdir -p) and retry
2. Check write permissions on the directory and fix with chmod/chown if needed
3. Verify the metadata file path in config (it must be a file path, not a directory, in an existing directory)
4. If on a read-only filesystem (container/CI), write to /tmp or mount a writable volume and point the metadata file there

Example fix

# before
hasura metadata export  # writing metadata to file: ... no such file or directory
# after
mkdir -p ./metadata && hasura metadata export  # with config metadata file ./metadata/metadata.[json|yaml]

// ensure the metadata file's directory exists and is writable before export
if dir := filepath.Dir(ec.MetadataFile); dir != "" {
  if _, err := os.Stat(dir); os.IsNotExist(err) {
    os.MkdirAll(dir, 0o755)
  }
  if f, err := os.CreateTemp(dir, ""); err != nil {
    return errors.New("metadata directory not writable")
  } else { f.Close(); os.Remove(f.Name()) }
}

if err := export(o, mode); err != nil {
  if strings.Contains(err.Error(), "writing metadata to file") {
    // fix directory permissions, mkdir -p, or change metadata file path
  }
}

When it happens

Trigger: `metadata export` when os.WriteFile to the metadata file path fails: parent directory missing, read-only filesystem, permission denied on the directory, path is a directory, or disk full.

Common situations: Config file pointing to a metadata file location whose directory was never created (common in fresh checkouts); running the CLI in a container or CI where the working dir is read-only; metadata file path configured as a relative path resolving to an unexpected location; disk quota exhausted.

Related errors

• exporting metadata from server: %w
• reading metadata from response: %w
• reading metadata file: %w
• creating metadata file %s failed: %w
• error building project metadata: %w

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