hasura/graphql-engine · error

expected a valid url for --api-host, parsing error: %w

Error message

expected a valid url for --api-host, parsing error: %w

What it means

Thrown in the console command's PreRunE when the --api-host flag value fails url.ParseRequestURI. The CLI requires api-host to be a parseable absolute URI before it can construct the console API proxy URL; malformed values (missing scheme, spaces, stray characters) are rejected up front.

Source

Thrown at cli/commands/console.go:76

				return errors.E(op, err)
			}

			if err := scripts.CheckIfUpdateToConfigV3IsRequired(ec); err != nil {
				return errors.E(op, err)
			}

			return nil
		},
		RunE: func(cmd *cobra.Command, args []string) error {
			op := genOpName(cmd, "RunE")
			if cmd.Flags().Changed("api-host") {
				var err error

				opts.APIHost, err = url.ParseRequestURI(apiHost)
				if err != nil {
					return errors.E(
						op,
						fmt.Errorf("expected a valid url for --api-host, parsing error: %w", err),
					)
				}
			} else {
				opts.APIHost = &url.URL{
					Scheme: "http",
					Host:   opts.Address,
				}
			}

			err := opts.Run()
			if err != nil {
				return errors.E(op, err)
			}

			return nil
		},
	}
	f := consoleCmd.Flags()

View on GitHub (pinned to 724551b9ae)

Solutions

1. Pass a full URI including scheme: `--api-host https://<host>` (port allowed: `https://host:port`).
2. Trim whitespace and check shell quoting of the flag value.
3. If you only meant to set the Hasura endpoint, use --endpoint instead.

Example fix

# before
hasura console --api-host localhost:9693
# after
hasura console --api-host http://localhost:9693

u, err := url.ParseRequestURI(apiHost)
if err != nil || !u.IsAbs() {
  log.Fatal("--api-host must be an absolute URL like https://host:port")
}

func isValidAPIHost(s string) bool { u, err := url.ParseRequestURI(s); return err == nil && u.IsAbs() }

Catch the parse error, prepend a scheme (http:// or https://) to the host value, and re-run the console command.

When it happens

Trigger: Passing `--api-host localhost:8080` (no scheme), `--api-host https://hasura console api host`, or any value with whitespace/invalid URI characters; only values like https://api.example.com parse.

Common situations: Assuming host:port is accepted like other flags, copying a URL with a trailing slash/space from docs, or shell quoting issues injecting extra characters.

Related errors

• framework %s is not found
• starter kit is not available for framework %s
• unknown shell: %s. Use bash or zsh
• cannot validate new config: %w
• expected extension to be one of %v but got %s on file %s

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