issuer URL scheme must be HTTPS unless development mode is e

Error message

issuer URL scheme must be HTTPS unless development mode is enabled

What it means

Hydra's Validate() enforces that the issuer URL uses the HTTPS scheme unless development mode is enabled. The issuer is embedded in tokens and exposed publicly, so plain HTTP is rejected to prevent token-issuer spoofing and insecure transport.

Source

Thrown at driver/config/helper.go:23

import (
	"context"
	"net/url"

	"github.com/pkg/errors"

	"github.com/ory/x/logrusx"
)

func Validate(ctx context.Context, l *logrusx.Logger, p *DefaultProvider) error {
	if p.IssuerURL(ctx).String() == "" && !p.IsDevelopmentMode(ctx) {
		l.Errorf("Configuration key `%s` must be set `dev` is `false`. To find out more, use `hydra help serve`.", KeyIssuerURL)
		return errors.New("issuer URL must be set unless development mode is enabled")
	}

	if p.IssuerURL(ctx).Scheme != "https" && !p.IsDevelopmentMode(ctx) {
		l.Errorf("Scheme from configuration key `%s` must be `https` when `dev` is `false`. Got scheme in value `%s` is `%s`. To find out more, use `hydra help serve`.", KeyIssuerURL, p.IssuerURL(ctx).String(), p.IssuerURL(ctx).Scheme)
		return errors.New("issuer URL scheme must be HTTPS unless development mode is enabled")
	}

	return nil
}

func urlRoot(u *url.URL) *url.URL {
	if u.Path == "" {
		u.Path = "/"
	}
	return u
}

View on GitHub (pinned to 4174065ffb)

Solutions

Change urls.issuer to use the https:// scheme, e.g. https://hydra.example.com
Set ORY_HYDRA_URLS_ISSUER to an https:// URL
For local development only, enable `dev: true` to allow http issuers

Example fix

// before
urls:
  issuer: http://hydra.example.com
// after
urls:
  issuer: https://hydra.example.com

Defensive patterns

Strategy: validation

Validate before calling

func validateIssuerScheme(issuer string) error {
    u, err := url.Parse(issuer)
    if err != nil {
        return err
    }
    if u.Scheme != "https" {
        return fmt.Errorf("issuer %q must use https", issuer)
    }
    return nil
}

Prevention

Only ever configure https:// issuer URLs outside local dev
Never relax with dev:true to work around prod config
Terminate TLS at the proxy but keep the issuer URL https://

When it happens

Trigger: Calling driver.New() where p.IssuerURL(ctx).Scheme != "https" (e.g. `urls.issuer: http://hydra.example.com`) while IsDevelopmentMode() is false.

Common situations: Pointing urls.issuer at http:// behind a TLS-terminating load balancer; using localhost http URLs copied from a dev setup into production; misconfigured reverse proxy meaning the issuer is http while the public endpoint is https.

Related errors

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