juanfont/headscale · error

running mock OIDC server: %w

Error message

running mock OIDC server: %w

What it means

Top-level wrap around mockOIDC() for the internal 'headscale mockoidc' command: the mock OpenID Connect server used in integration testing failed to start or run. The wrapped error identifies the stage — missing env config (client id/issuer), bad listening address, or a runtime failure of the embedded OIDC provider.

Source

Thrown at cmd/headscale/cli/mockoidc.go:42

	errMockOidcUsersNotDefined        = errors.New("MOCKOIDC_USERS not defined")
)

const refreshTTL = 60 * time.Minute

var accessTTL = 2 * time.Minute

func init() {
	rootCmd.AddCommand(mockOidcCmd)
}

var mockOidcCmd = &cobra.Command{
	Use:   "mockoidc",
	Short: "Runs a mock OIDC server for testing",
	Long:  "This internal command runs a OpenID Connect for testing purposes",
	RunE: func(cmd *cobra.Command, args []string) error {
		err := mockOIDC()
		if err != nil {
			return fmt.Errorf("running mock OIDC server: %w", err)
		}

		return nil
	},
}

func mockOIDC() error {
	clientID := os.Getenv("MOCKOIDC_CLIENT_ID")
	if clientID == "" {
		return errMockOidcClientIDNotDefined
	}

	clientSecret := os.Getenv("MOCKOIDC_CLIENT_SECRET")
	if clientSecret == "" {
		return errMockOidcClientSecretNotDefined
	}

	addrStr := os.Getenv("MOCKOIDC_ADDR")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Set the required env vars — at minimum MOCKOIDC_CLIENT_ID (check mockoidc.go for the full list: issuer, addr, client secret)
2. Free the configured listen port (kill stale mockoidc processes)
3. Run it inside the integration environment that normally configures it, rather than ad hoc

Example fix

# before
headscale mockoidc

# after
export MOCKOIDC_CLIENT_ID=test-client
headscale mockoidc

for _, k := range []string{"MOCKOIDC_CLIENT_ID" /* + issuer/addr per mockoidc.go */} {
	if os.Getenv(k) == "" {
		log.Fatalf("required env %s not set", k)
	}
}

if err := mockOIDC(); err != nil {
	log.Fatalf("mock oidc failed: %v", err) // fail the harness fast, surface wrapped cause
}

When it happens

Trigger: Running 'headscale mockoidc' without the required environment variables (e.g., MOCKOIDC_CLIENT_ID unset yields errMockOidcClientIDNotDefined), with an invalid issuer URL, or when its listen port is already taken.

Common situations: Integration test harness misconfiguration (env vars not exported); port conflicts when a previous mock server did not shut down; running the command outside the test container where /etc/headscale networking assumptions do not hold.

Related errors

• invalid alias: %w
• resolving: %w
• invalid destination %q: %w
• resolving destination: %w
• %w: %q

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/346941d515ed1a26. Report an issue: GitHub.