ory/hydra · error

could not parse the endpoint URL "%s"

Error message

could not parse the endpoint URL "%s"

What it means

cmdx.NewClient parses the resolved endpoint URL with url.Parse after trimming trailing slashes. If parsing fails (malformed URL), the error is wrapped with this message including the raw endpoint value. Parsing rarely fails on its own — this usually indicates a garbage value like 'http://[::1' or stray characters/newlines.

Source

Thrown at oryx/cmdx/http.go:80

// NewClient creates a new HTTP client.
func NewClient(cmd *cobra.Command) (*http.Client, *url.URL, error) {
	endpoint, err := cmd.Flags().GetString(FlagEndpoint)
	if err != nil {
		return nil, nil, errors.WithStack(err)
	}

	if endpoint == "" {
		endpoint = os.Getenv(envKeyEndpoint)
	}

	if endpoint == "" {
		return nil, nil, errors.Errorf("you have to set the remote endpoint, try --help for details")
	}

	u, err := url.Parse(strings.TrimRight(endpoint, "/"))
	if err != nil {
		return nil, nil, errors.Wrapf(err, `could not parse the endpoint URL "%s"`, endpoint)
	}

	hc := retryablehttp.NewClient().StandardClient()
	hc.Timeout = time.Second * 10

	rawHeaders, err := cmd.Flags().GetStringSlice(FlagHeaders)
	if err != nil {
		return nil, nil, errors.WithStack(err)
	}
	header := http.Header{}
	for _, h := range rawHeaders {
		parts := strings.Split(h, ":")
		if len(parts) != 2 {
			_, _ = fmt.Fprintf(cmd.OutOrStdout(), "Unable to parse `--http-header` flag. Format of flag value is a `: ` delimited string like `--http-header 'Some-Header: some-values; other values`. Received: %v", rawHeaders)
			return nil, nil, FailSilently(cmd)
		}

		for k := range parts {

View on GitHub (pinned to 4174065ffb)

Solutions

1. Print and inspect the endpoint value (echo "$VAR" | cat -A) to find hidden whitespace/control characters and correct it
2. Fix the URL syntax (e.g. balance IPv6 brackets: http://[::1]:4444)
3. Remove surrounding quotes or stray characters introduced by shell/config files
4. Parse the URL locally with a small Go snippet using url.Parse to confirm it is valid before retrying

Example fix

// before
export ORY_URL="https://hydra.example.com "  # trailing space/newline
// after
export ORY_URL=https://hydra.example.com

u, err := url.Parse(strings.TrimRight(endpoint, "/"))
if err != nil {
    return fmt.Errorf("endpoint %q is not a valid URL: %w", endpoint, err)
}

client, err := cmdx.NewClient(cmd)
if err != nil && strings.Contains(err.Error(), "could not parse the endpoint URL") {
    log.Errorf("check ORY_URL/env value for whitespace or malformed URL: %v", err)
    return err
}

When it happens

Trigger: Providing an endpoint (flag or env var) that url.Parse rejects — e.g. unbalanced brackets in IPv6, control characters/whitespace/newlines in the env var, or an otherwise malformed URL string.

Common situations: Trailing whitespace or '\r' in env vars set from files; copy-paste artifacts (quotes or spaces) in the endpoint; malformed IPv6 literal URLs.

Related errors

• A DSN is required as a positional argument when not passing
• When using flag -e, environment variable DSN must be set. Wh
• unable to decode JSON: %w
• %w: in source %q: allowed schemes: %s
• Could not create driver

AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03). Data as JSON: /api/errors/154052d95f9f311b. Report an issue: GitHub.