{"record":{"id":"fe40e387b2baa56f","repo":"gravitational/teleport","slug":"user-not-managed-by-teleport","errorCode":null,"errorMessage":"user not managed by teleport","messagePattern":"user not managed by teleport","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"lib/srv/usermgmt.go","lineNumber":289,"sourceCode":"\t\tfmt.Fprintf(&sudoersOut, \"%s %s\\n\", name, entry)\n\t}\n\terr := u.backend.WriteSudoersFile(name, []byte(sudoersOut.String()))\n\tif errors.Is(err, host.ErrInvalidSudoers) {\n\t\tu.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)\n\t\treturn trace.BadParameter(\"invalid sudoers entry for login %q, inspect roles' host_sudoers field or static host user's sudoers field for invalid syntax\", name)\n\t}\n\treturn trace.Wrap(err)\n}\n\nfunc (u *HostSudoersManagement) RemoveSudoers(name string) error {\n\tif err := u.backend.RemoveSudoersFile(name); err != nil {\n\t\treturn trace.Wrap(err)\n\t}\n\treturn nil\n}\n\n// errUnmanagedUser is returned when attempting to modify or interact with a user that is not managed by Teleport.\nvar errUnmanagedUser = errors.New(\"user not managed by teleport\")\n\n// errStaticConversion is returned when attempting to convert a managed host user to or from a static host user\nvar errStaticConversion = errors.New(\"managed host users can not be converted to or from a static host user\")\n\nfunc (u *HostUserManagement) updateUser(hostUser HostUser, ui *decisionpb.HostUsersInfo) error {\n\tctx := u.ctx\n\tlog := u.log.With(\n\t\t\"host_username\", hostUser.Name,\n\t\t\"mode\", ui.GetMode(),\n\t\t\"uid\", hostUser.UID,\n\t\t\"gid\", hostUser.GID,\n\t)\n\n\tif ui.GetMode() == decisionpb.HostUserMode_HOST_USER_MODE_KEEP {\n\t\t_, hasKeepGroup := hostUser.Groups[apiconstants.TeleportKeepGroup]\n\t\tif !hasKeepGroup {\n\t\t\thome, err := u.backend.GetDefaultHomeDirectory(hostUser.Name)\n\t\t\tif err != nil {","sourceCodeStart":271,"sourceCodeEnd":307,"githubUrl":"https://github.com/gravitational/teleport/blob/1283425b60ec5f60d509ba4c791183d452923ff7/lib/srv/usermgmt.go#L271-L307","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Either manually delete the existing user from the machine so Teleport can recreate it as managed","Add 'teleport-keep' to the host_groups defined in the user's role to adopt (migrate) the existing user","Set the role option to explicitly manage existing users if you want Teleport to take over the account","Verify the login does not accidentally match a system account (e.g. root, service users)"],"exampleFix":"// before: role does not manage existing user\n// user 'alice' exists locally, not in teleport groups -> errUnmanagedUser\n// after: add teleport-keep to role host_groups\nhost_groups:\n  - teleport-keep\n  - access","handlingStrategy":"validation","validationCode":"// before upsert: verify ownership of the account\nmanaged, err := isTeleportManagedUser(name)\nif err != nil { return trace.Wrap(err) }\nif !managed && !options.allowMigration {\n    log.DebugContext(ctx, \"skipping unmanaged user\", \"login\", name)\n    return nil\n}","typeGuard":"func isUnmanagedUserErr(err error) bool { return errors.Is(err, errUnmanagedUser) }","tryCatchPattern":"if err := u.upsertHostUser(name, ui); err != nil {\n    if errors.Is(err, errUnmanagedUser) {\n        log.WarnContext(ctx, \"user not managed by teleport; add teleport-keep to host_groups or delete the local user\")\n        return nil\n    }\n    return trace.Wrap(err)\n}","preventionTips":["Add 'teleport-keep' to host_groups to adopt pre-existing users","Avoid logins colliding with system account names","Audit servers for pre-existing accounts matching role logins before enabling host user creation"],"tags":["host-users","user-management","linux"],"backgroundTag":"unmanaged-host-user","analyzedSha":"1283425b60ec5f60d509ba4c791183d452923ff7","analyzedAt":"2026-09-02T04:06:41.601Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}