juanfont/headscale · error

user not empty: node(s) found

Error message

user not empty: node(s) found

What it means

Error "user not empty: node(s) found" thrown in juanfont/headscale.

Source

Thrown at hscontrol/db/users.go:17

package db

import (
	"errors"
	"fmt"
	"strconv"
	"testing"

	"github.com/juanfont/headscale/hscontrol/types"
	"github.com/juanfont/headscale/hscontrol/util"
	"gorm.io/gorm"
)

var (
	ErrUserExists        = errors.New("user already exists")
	ErrUserNotFound      = errors.New("user not found")
	ErrUserStillHasNodes = errors.New("user not empty: node(s) found")
	ErrUserNotUnique     = errors.New("expected exactly one user")
)

func (hsdb *HSDatabase) CreateUser(user types.User) (*types.User, error) {
	return Write(hsdb.DB, func(tx *gorm.DB) (*types.User, error) {
		return CreateUser(tx, user)
	})
}

// CreateUser creates a new [types.User]. Returns error if could not be created
// or another user already exists.
func CreateUser(tx *gorm.DB, user types.User) (*types.User, error) {
	err := util.ValidateUsername(user.Name)
	if err != nil {
		return nil, err
	}

	err = tx.Create(&user).Error

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (user not empty); 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 (user not empty); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at hscontrol/db/users.go:17 when the library encounters an invalid state.

Common situations: A user cannot be destroyed while nodes are still registered to it. Delete or move the user's nodes first, then destroy the user.

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