hasura/graphql-engine · error

failed to export metadata: %w

Error message

failed to export metadata: %w

What it means

In directory metadata mode, Export first calls projectmetadata.Handler.ExportMetadata to pull metadata from the server and write it into project files; failure of that handler is wrapped here. The wrapped error may be an API failure (auth/network) or a filesystem failure writing the metadata files into the project.

Source

Thrown at cli/commands/metadata_handlers.go:45

	case cli.MetadataModeYAML:
		return &metadataModeYAMLHandler{}
	default:
		return &metadataModeDirectoryHandler{}
	}
}

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 {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the wrapped error: 'permission denied'/'read-only file system' means a filesystem issue; HTTP statuses mean an API issue
2. Fix directory permissions on the metadata/ folder or remount read-write
3. Verify endpoint/admin-secret if the failure is server-side
4. Retry after freeing disk space if ENOSPC appears in the chain

# Shell: ensure metadata dir is writable and server reachable
touch metadata/.write_test && rm metadata/.write_test || { echo 'metadata dir not writable'; exit 1; }
curl -fsS "$ENDPOINT/healthz" >/dev/null || { echo 'server unreachable'; exit 1; }

// Go: classify failure source
if err := handler.ExportMetadata(); err != nil {
  var pathErr *os.PathError
  if errors.As(err, &pathErr) {
    // local filesystem problem
  } else {
    // server/API problem
  }
}

When it happens

Trigger: Running `hasura metadata export` in a project when the export API call fails or when writing exported files to the metadata directory fails (read-only directory, permission denied, disk full).

Common situations: CI containers running as non-root users without write access to the mounted project, read-only checkouts, admin secret/endpoint misconfigurations, or disk quota exhaustion on workstations.

Related errors

• failed to export metadata: %w
• cannot write metadata to project: %w
• error generating codegen for action %s: %w
• error in fetching codegen frameworks: %w
• error in copying starter kit: %w

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