hasura/graphql-engine · error

cannot create metadata directory: %w

Error message

cannot create metadata directory: %w

What it means

A generic 'not supported' error whose reason string explains the specific unsupported operation. It is returned when the resolver encounters a construct or combination it explicitly does not support, distinct from syntax errors.

Source

Thrown at cli/cli.go:793

			case ".yaml":
				ec.MetadataMode = MetadataModeYAML
			default:
				return errors.E(
					op,
					stderrors.New(
						"unrecogonized file extension. only .json/.yaml files are allowed for value of metadata_file",
					),
				)
			}
		}
		// set name of metadata directory
		ec.MetadataDir = filepath.Join(ec.ExecutionDirectory, ec.Config.MetadataDirectory)

		_, err := os.Stat(ec.MetadataDir)
		if err != nil && stderrors.Is(err, fs.ErrNotExist) && len(ec.MetadataFile) == 0 {
			err = os.MkdirAll(ec.MetadataDir, os.ModePerm)
			if err != nil {
				return errors.E(op, fmt.Errorf("cannot create metadata directory: %w", err))
			}
		}
	}

	ec.Logger.Debug("graphql engine endpoint: ", ec.Config.Endpoint)
	ec.Logger.Debug(strings.Repeat("*", len(ec.Config.AdminSecret)))

	uri, err := url.Parse(ec.Config.Endpoint)
	if err != nil {
		return errors.E(op, fmt.Errorf("error while parsing the endpoint :%w", err))
	}

	// check if server is using metadata v3
	if ec.Config.APIPaths.V1Query != "" {
		uri.Path = path.Join(uri.Path, ec.Config.APIPaths.V1Query)
	} else {
		uri.Path = path.Join(uri.Path, "v1/query")
	}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the {reason} text — it names the exact unsupported operation
2. Restructure the metadata to avoid the unsupported combination
3. Upgrade to a version where the operation is supported, if available

match resolve(&md) {
    Err(ResolveError::NotSupported { reason }) => { log::warn!("unsupported: {reason}"); simplified_fallback(&md) }
    r => r,
}

When it happens

Trigger: Any resolution path hitting an explicitly unimplemented branch, e.g. unsupported data connector capability combinations, unsupported type representations, or disallowed metadata shapes; the reason field is populated by the throwing code.

Common situations: Using a data connector feature not supported for the given operation; combining metadata options the resolver disallows; running into known limitations of an early/experimental version.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• cannot create migrations directory: %w
• boolean expressions with aggregate operands are not supporte
• Predicate types in data connectors are unsupported
• the boolean expression '{type_name}' has enabled logical ope
• error fetching config from server: %w

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