What causes "error in converting metadata to sdl: %w" in hasura/graphql-engine?

Run with a recent CLI version so the matching cli-extension is fetched (retry after `hasura update-cli` or reinstall)

error in converting metadata to sdl: %w

Error message

error in converting metadata to sdl: %w

What it means

Thrown by Actions.Create when no intro schema is provided and the CLI must generate default SDL by calling the cli-extension server's ConvertMetadataToSDL endpoint; that call failed. The underlying error from the extension is wrapped in the message.

Source

Thrown at cli/internal/metadataobject/actions/actions.go:120

}

input SampleInput {
	username: String!
	password: String!
}
`
	} else {
		sdlToReq := types.SDLToRequest{
			Derive: types.DerivePayload{
				IntrospectionSchema: introSchema,
				Operation:           deriveFrom,
				ActionName:          name,
			},
		}

		sdlToResp, err := a.cliExtensionConfig.ConvertMetadataToSDL(sdlToReq)
		if err != nil {
			return errors.E(op, fmt.Errorf("error in converting metadata to sdl: %w", err))
		}

		defaultSDL = sdlToResp.SDL.Complete
	}

	graphqlFileContent = defaultSDL + "\n" + graphqlFileContent

	data, err := editor.CaptureInputFromEditor(
		editor.GetPreferredEditorFromEnvironment,
		graphqlFileContent,
		"graphql",
	)
	if err != nil {
		return errors.E(op, fmt.Errorf("error in getting input from editor: %w", err))
	}

	sdlFromReq := types.SDLFromRequest{
		SDL: types.SDLPayload{

View on GitHub (pinned to 724551b9ae)

Solutions

Run with a recent CLI version so the matching cli-extension is fetched (retry after `hasura update-cli` or reinstall)
Clear and re-download the extension cache, then retry
Pass a non-nil introSchema to skip the ConvertMetadataToSDL path entirely
Check the wrapped error for extension process/startup details

Defensive patterns

Strategy: fallback

Validate before calling

// Ensure a matching cli-extension is available before calling Create
if _, err := os.Stat(cliExtensionPath()); err != nil {
	// reinstall CLI / download extension before proceeding
}

Try / catch

if err := actions.Create(name, derive, nil, false); err != nil {
	if strings.Contains(err.Error(), "converting metadata to sdl") {
		// retry once after ensuring extension present; or supply introSchema to bypass
	}
	return err
}

Prevention

Keep CLI and cli-extension versions in sync via official installs
Pass an introSchema when you don't need extension-generated defaults
Pin CLI versions in CI to avoid extension download mismatches

When it happens

Trigger: Calling Create with introSchema == nil so the default Mutation scaffolding must be rendered via the cli-extension (a bundled Node binary); the extension process fails to start, its HTTP endpoint errors, or it's missing/incompatible with the host platform.

Common situations: The cli-extension binary isn't downloaded or is corrupted, an unsupported OS/arch, node runtime issues in sandboxed CI, or a version mismatch between CLI and extension where the convert endpoint changed.

Related errors

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