juanfont/headscale · error

creating preauth key with tags: %w

Error message

creating preauth key with tags: %w

What it means

Returned by Scenario.CreatePreAuthKeyWithTags at the pre-check: no headscale control server is available (errNoHeadscaleAvailable) because s.Headscale() failed. The key-with-tags variant can never reach the gRPC layer without a running control server.

Source

Thrown at integration/scenario.go:562

	key, err := headscale.CreateAuthKeyWithOptions(opts)
	if err != nil {
		return nil, fmt.Errorf("creating preauth key with options: %w", err)
	}

	return key, nil
}

// CreatePreAuthKeyWithTags creates a "pre authorised key" with the specified tags
// to be created in the Headscale instance on behalf of the [Scenario].
func (s *Scenario) CreatePreAuthKeyWithTags(
	user uint64,
	reusable bool,
	ephemeral bool,
	tags []string,
) (*clientv1.PreAuthKey, error) {
	headscale, err := s.Headscale()
	if err != nil {
		return nil, fmt.Errorf("creating preauth key with tags: %w", errNoHeadscaleAvailable)
	}

	key, err := headscale.CreateAuthKeyWithTags(user, reusable, ephemeral, tags)
	if err != nil {
		return nil, fmt.Errorf("creating preauth key with tags: %w", err)
	}

	return key, nil
}

// CreateUser creates a [User] to be created in the
// Headscale instance on behalf of the [Scenario].
func (s *Scenario) CreateUser(user string) (*clientv1.User, error) {
	if headscale, err := s.Headscale(); err == nil { //nolint:noinlineerr
		u, err := headscale.CreateUser(user)
		if err != nil {
			return nil, fmt.Errorf("creating user: %w", err)
		}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Diagnose headscale startup: inspect the error from scenario.Headscale() and `docker logs` of the control container
2. Run tests through `go run ./cmd/hi run "TestName"` so the Docker environment is prepared
3. Ensure the call happens during the scenario's live phase, not after teardown

if _, err := scenario.Headscale(); err != nil {
    t.Fatalf("control server unavailable: %v", err)
}

key, err := scenario.CreatePreAuthKeyWithTags(u.Id, false, false, tags)
if err != nil {
    t.Fatalf("preauth key with tags failed: %v", err)
}

When it happens

Trigger: Calling CreatePreAuthKeyWithTags when the headscale container never started or was already torn down.

Common situations: Earlier Scenario.Headscale() failure being masked; calling the helper after Shutdown; test running without the hi-managed Docker environment.

Related errors

• creating user: %w
• auth-key expired
• auth-key has already been used
• user mismatch
• failed to parse auth-key

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