juanfont/headscale · error

at least one --scope is required: %w

Error message

at least one --scope is required: %w

What it means

Error "at least one --scope is required: %w" thrown in juanfont/headscale.

Source

Thrown at cmd/headscale/cli/oauth_client.go:63

	Long: `Create a general-purpose OAuth client. It authenticates with the OAuth 2.0
client-credentials grant and mints short-lived, scope-limited access tokens.
The wire format is compatible with Tailscale tooling (the Terraform provider,
the Kubernetes operator, tscli, ...), so those can drive Headscale unchanged.

The client secret is shown ONCE on creation and cannot be retrieved again; if
you lose it, delete the client and create a new one.

Scopes gate what the client's tokens may do; tags are the device tags those
tokens may assign and are required when the scopes include devices:core or
auth_keys.`,
	Aliases: []string{"c", cmdNew},
	RunE: func(cmd *cobra.Command, _ []string) error {
		scopes, _ := cmd.Flags().GetStringArray("scope")
		tags, _ := cmd.Flags().GetStringArray("tag")
		description, _ := cmd.Flags().GetString("description")

		if len(scopes) == 0 {
			return fmt.Errorf("at least one --scope is required: %w", errMissingParameter)
		}

		ctx, client, cancel, err := newV2Client()
		if err != nil {
			return err
		}
		defer cancel()

		keyType := "client"

		resp, err := client.CreateKeyWithResponse(ctx, oauthTailnet, clientv2.CreateKeyRequest{
			KeyType:     &keyType,
			Scopes:      &scopes,
			Tags:        &tags,
			Description: &description,
		})
		if err != nil {
			return fmt.Errorf("creating oauth client: %w", err)

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (at least one --scope is required); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (at least one --scope is required); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at cmd/headscale/cli/oauth_client.go:63 when the library encounters an invalid state.

Common situations: Creating an OAuth client requires at least one --scope flag. Pass one or more scopes, e.g. --scope openid.

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