gravitational/teleport · warning

user not managed by teleport

Error message

user not managed by teleport

What it means

errUnmanagedUser is returned when Teleport attempts to modify or interact with a host user account that was not created by Teleport and is not in the managed groups. UpsertHostUser/UpsertUser refuse to alter such users to avoid clobbering system accounts. The SSH session handler treats this as non-fatal: it logs a warning and continues without creating the user.

Source

Thrown at lib/srv/usermgmt.go:289

		fmt.Fprintf(&sudoersOut, "%s %s\n", name, entry)
	}
	err := u.backend.WriteSudoersFile(name, []byte(sudoersOut.String()))
	if errors.Is(err, host.ErrInvalidSudoers) {
		u.log.WarnContext(context.Background(), "Invalid sudoers entry. If using a login managed by a static host user resource, inspect its configured sudoers field for invalid entries. Otherwise, inspect the host_sudoers field for roles targeting this host.", "error", err, "host_username", name)
		return trace.BadParameter("invalid sudoers entry for login %q, inspect roles' host_sudoers field or static host user's sudoers field for invalid syntax", name)
	}
	return trace.Wrap(err)
}

func (u *HostSudoersManagement) RemoveSudoers(name string) error {
	if err := u.backend.RemoveSudoersFile(name); err != nil {
		return trace.Wrap(err)
	}
	return nil
}

// errUnmanagedUser is returned when attempting to modify or interact with a user that is not managed by Teleport.
var errUnmanagedUser = errors.New("user not managed by teleport")

// errStaticConversion is returned when attempting to convert a managed host user to or from a static host user
var errStaticConversion = errors.New("managed host users can not be converted to or from a static host user")

func (u *HostUserManagement) updateUser(hostUser HostUser, ui *decisionpb.HostUsersInfo) error {
	ctx := u.ctx
	log := u.log.With(
		"host_username", hostUser.Name,
		"mode", ui.GetMode(),
		"uid", hostUser.UID,
		"gid", hostUser.GID,
	)

	if ui.GetMode() == decisionpb.HostUserMode_HOST_USER_MODE_KEEP {
		_, hasKeepGroup := hostUser.Groups[apiconstants.TeleportKeepGroup]
		if !hasKeepGroup {
			home, err := u.backend.GetDefaultHomeDirectory(hostUser.Name)
			if err != nil {

View on GitHub (pinned to 1283425b60)

Solutions

1. Either manually delete the existing user from the machine so Teleport can recreate it as managed
2. Add 'teleport-keep' to the host_groups defined in the user's role to adopt (migrate) the existing user
3. Set the role option to explicitly manage existing users if you want Teleport to take over the account
4. Verify the login does not accidentally match a system account (e.g. root, service users)

Example fix

// before: role does not manage existing user
// user 'alice' exists locally, not in teleport groups -> errUnmanagedUser
// after: add teleport-keep to role host_groups
host_groups:
  - teleport-keep
  - access

// before upsert: verify ownership of the account
managed, err := isTeleportManagedUser(name)
if err != nil { return trace.Wrap(err) }
if !managed && !options.allowMigration {
    log.DebugContext(ctx, "skipping unmanaged user", "login", name)
    return nil
}

func isUnmanagedUserErr(err error) bool { return errors.Is(err, errUnmanagedUser) }

if err := u.upsertHostUser(name, ui); err != nil {
    if errors.Is(err, errUnmanagedUser) {
        log.WarnContext(ctx, "user not managed by teleport; add teleport-keep to host_groups or delete the local user")
        return nil
    }
    return trace.Wrap(err)
}

When it happens

Trigger: UpsertHostUser or UpsertUser encounters an existing Linux account that does not belong to any teleport-keep group and migration is not explicitly enabled; a session login targets a local user Teleport doesn't manage.

Common situations: A user pre-existed on the machine before Teleport host user creation was enabled; role host_groups changed and the account predates management; operator declined the 'teleport-keep' migration.

Related errors

• User logged in error
• managed host users can not be converted to or from a static
• elevated credential activation not implemented for linux

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/fe40e387b2baa56f. Report an issue: GitHub.