issuer URL must be set unless development mode is enabled

Error message

issuer URL must be set unless development mode is enabled

What it means

Hydra's Validate() in driver/config requires an issuer URL (config key `urls.issuer`) unless development mode (`dev: true`) is enabled. The issuer URL is the base URL embedded in issued tokens and must be present for OAuth2 to function. Without it (and without dev mode), the server refuses to start.

Source

Thrown at driver/config/helper.go:18

// Copyright © 2022 Ory Corp
// SPDX-License-Identifier: Apache-2.0

package config

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

Set `urls.issuer` in the Hydra config file, e.g. urls: { issuer: https://my-hydra.example.com }
Set the environment variable SERVE_PUBLIC/... — specifically ORY_HYDRA_URLS_ISSUER=https://my-hydra.example.com
For local development only, start Hydra with `dev: true` (never in production) to bypass the issuer requirement

Example fix

// before (hydra.yml)
serve: {}
// after
urls:
  issuer: https://hydra.example.com

Defensive patterns

Strategy: validation

Validate before calling

func validateIssuer(cfg *hydraConfig) error {
    if cfg.URLs == nil || cfg.URLs.Issuer == "" && !cfg.Dev {
        return errors.New("urls.issuer must be set (or enable dev mode for local testing)")
    }
    return nil
}

Prevention

Always set urls.issuer in every environment's config, including local
Keep issuer constant per environment — it is embedded in issued tokens
Use a config linter or startup smoke test that calls driver.New in CI

When it happens

Trigger: Calling driver.New() with a DefaultProvider whose IssuerURL() returns an empty string while IsDevelopmentMode() is false — e.g. `urls.issuer` not set in config and no ORY_HYDRA_URLS_ISSUER environment variable provided.

Common situations: Fresh Hydra deployments where the operator forgot to set urls.issuer; running the official production Docker image (dev mode off by default) with a minimal config; migrating from dev to production config and dropping the issuer key.

Related errors

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