Recovering ERPNext admin access after a lockout

Recovering ERPNext admin access after a lockout starts with knowing who can still reach the server

If an administrator has removed their own System Manager role or lost the Administrator password, nobody can change settings from the browser, and the first question is not how to reset anything. It is who still has a working route to the server. Recovery from a lockout depends on shell access to the bench or Docker host and on access to the database behind the site. In-app recovery only helps users who still hold a System Manager role and can sign in. If no such user exists, or if the only remaining System Manager account is compromised or unknown, you are no longer dealing with a forgotten password. You are dealing with an access-governance gap, and the fix belongs in your change process as well as in the server console.

Before touching anything, inventory the paths in. List every account that holds System Manager, every person with SSH or console access to the bench host or container, and every credential stored for the database and the site. Confirm whether the site is on a self-managed host you control or on a managed platform where shell access is not yours to use. On a managed platform, the vendor's support process is the route, and you should confirm that process before an incident rather than during one. Also check whether LDAP or social login is the only sign-in method, since a password reset through the bench does not change how those users authenticate. Ask your team to confirm which of these paths work today, because a lockout is the wrong moment to learn that a jump host account has expired.

For the Administrator password itself, the documented bench command is bench --site [sitename] set-admin-password, which resets the Administrator password for the named site. Run it from the bench directory on the host that serves the site, and record who ran it, when, and why, because the Administrator account is the most privileged login on the site. Treat that record as part of your access review, not as housekeeping. Plan the same discipline for any break-glass account you create later, so that the path you use in an emergency is tested, owned and logged rather than remembered by one engineer.

Choosing a recovery path by what you still have

If another user with the System Manager role can still sign in, that colleague is your fastest recovery path and it causes the least disruption. The usual cause is a role edit made to your own account, so the fix is a role change made inside the application itself, carried out by someone who already has the access to make it.

First action: the working System Manager opens your User record, re-adds the System Manager role, and saves. Check the full role list before saving so no other roles are removed by accident.
Who performs it: an active System Manager other than you, acting under your access change process. Confirm that account is not affected by the same cause.
Evidence to keep: your user name, the time of the change, the person who made it, the roles before and after, and the ticket that approved it.
Verify after the change: sign out, sign in again, and confirm that the Desk pages you need now appear. Confirm in your own environment whether a new session is required before the role takes effect.
Record the cause: find out whether the role was removed deliberately or through a bulk import or script. Record the finding for your next access review.

Before you act, confirm that the working account is the one your access policy names as a System Manager, because a lockout is a poor moment to discover that the backup account is also out of date.

When the Administrator password is lost but no System Manager session is available, recovery is a server-side reset. Frappe's bench command set-admin-password resets the Administrator password for a named site. Whoever runs it needs shell access to the bench host and authority over that site, so this belongs with the platform team and should never be a request a user submits through a form.

First action: on the bench host, run bench --site [sitename] set-admin-password and follow the prompt. Confirm the exact syntax in the bench commands cheatsheet before running it in production.
Who performs it: a platform engineer with bench-user or root access to the server, under an approved change with a named owner.
Store the new secret: place the new password in your approved secret store right away, with restricted access. Do not paste it into tickets, chat or email.
Evidence to keep: the date and time, the host and site name, the operator, the change reference, and the sign-in test that followed.
Verify sign-in: sign in as Administrator from a clean session, then confirm that the administrator activity appears in the logs you have chosen to retain. Confirm how your site records that activity.

Check that the reset is the only change made during the window, because a rushed session on the host is where unrelated configuration drift tends to enter.

Recover access step by step on a self-hosted bench

This sequence restores administrator access to a self-hosted ERPNext site by resetting the Administrator password from the bench command line, then returning a named user to the intended roles. Each step ends with a check so you know the site and the access path work before you move on.

Confirm the site name and bench directory
Log in to the server that runs the site as the user who owns the bench, usually the frappe user on a standard install. Change into the bench directory and list the sites in the sites folder, or check sites/currentsite.txt if it exists, to confirm the exact site name you will target. Use the name as Frappe lists it, because a typo will either fail or point at the wrong site. Done when the site name matches the domain your users visit and the bench directory contains a sites folder with that site.
Confirm the site responds before changing anything
Run bench --site [sitename] console or open the site in a browser to confirm the web service and database connection are working. If the site does not load, fix the service or database problem first, because a password reset will not help when the app cannot reach its database. Record the current state of the Administrator and the affected user, including which roles they hold, so you can compare after recovery. Done when the login page loads and you have a written note of the current roles.
Reset the Administrator password from the bench
Run bench --site [sitename] set-admin-password and enter a new password when prompted, using a value stored in your password manager. This command resets the Administrator password directly in the database, so it works even when you cannot sign in through the web interface. Keep the command output, and do not paste the new password into tickets or chat. Done when the command completes without an error message.
Sign in as Administrator and verify access
Open the site in a browser and sign in as Administrator with the new password. Check that the desk loads and that you can open the User list. If you are prompted for a second factor, confirm which device or recovery method applies, because the bench command does not bypass two-factor authentication. Done when you reach the desk and the User list opens without a permission error.
Restore intended roles on the named user
Open the affected user record from the User list, review the Roles section, and add or remove roles so the account matches the access model your organization approved. Save the record and note the change in your change log. Avoid giving System Manager by default, because that role grants broad control over the site. Done when the saved user shows the expected roles and the change appears in the record's version history.
Check that the restored user can work
Sign out of Administrator, then sign in as the restored user with a test session or their own credentials after a password reset. Confirm the user can open Role Permission Manager if the role should allow it, and that they can see the DocTypes they need and nothing beyond them. Compare the result with the baseline note from the second step. Done when the user's visible modules and the permission screen match the approved role design.
Close the recovery and record the cause
Sign out of Administrator and confirm that the Administrator account is still needed for break-glass use only. Record which roles were removed, how the password was reset, who approved the change, and what caused the lockout, such as removing the last System Manager user. Check your backup and hosting access notes. If you run Frappe Cloud or a managed host, confirm with the provider which access routes they offer before you rely on any bench command. Done when the incident record is complete and the access route for the next recovery is confirmed.

Break-glass account options compared

This table compares three ways to keep a way back into ERPNext when normal logins fail: a dedicated local System Manager account, a credential held in a vault, an SSO-independent account protected by a hardware-backed second factor, and relying only on bench access. Read each row against your identity setup, because the right choice depends on whether your users sign in through LDAP or social login and who can reach the server shell. The main takeaway is that a break-glass path is only useful if it is tested and kept separate from the accounts it is meant to back up.

Option	When it fits	What it protects against	Operational cost
Dedicated local System Manager account	Sites where most users sign in through LDAP or social login and you need a local login that still works when the identity provider is down	Lockout from removing your own role or an SSO outage, provided the account's password and 2FA status are confirmed in System Settings	Someone must own the password, rotate it, review its use and test the login on a schedule
Stored credential in a vault	Teams that already run a secrets manager and want the break-glass password released only under a documented procedure	Loss of the password held by one person, and unrecorded use if access to the vault is logged	Vault access rules, approval steps and a recovery path for the vault itself must be maintained
SSO-independent account with a hardware-backed second factor	Regulated sites where the recovery login must not depend on the identity provider and the second factor must resist phishing	Compromise of a password alone and failure of the identity provider, subject to confirming the supported 2FA methods for this account type	Hardware keys need issuing, a spare key stored securely and a check that 2FA is enforced for this account
Bench access only	Small sites where a trusted administrator already has server shell access and the site runs on infrastructure you control	Lockout of every application account, since the bench command set-admin-password resets the Administrator password	Relies on shell access staying available and controlled, and the command still needs a logged, reviewed procedure

Preventing the next lockout with role design and break-glass controls

Most ERPNext lockouts come from one account, one role change or one directory update made without a way back in. The four practices below give you a second route into the system, a tested login path, tighter control over role edits and a check on LDAP mappings before they take effect.

Keep two named System Manager accounts

Keep at least two named users with the System Manager role who are not synced from your directory and who are not used for daily work. Each should have a personal login so changes can be traced to a person. Check the Role Permission list and the User list each quarter to confirm both accounts are active, enabled and still hold the role. If the only admin is a directory-synced user, a directory outage or group change can remove access to the whole site.

Record and test the break-glass login

Store the break-glass credentials in your organization's sealed secrets process, with the procedure for using them written next to the storage location. Once a quarter, log in with the break-glass account, confirm it reaches the Desk, then log out and record the result. A login path that has never been exercised is not a recovery path. Note who holds the second factor, if two-factor authentication is enforced for that account.

Restrict who can edit roles

Role changes take effect for every user holding that role, so limit edit rights on Role, Role Profile and Role Permission Manager to a small named group. Review which users hold System Manager and which can edit DocPerm rows, because a user who can change permissions can also remove their own access. Ask your implementation partner or internal admin to confirm this list in writing before go-live and after each upgrade.

Review LDAP group mappings before directory changes

If ERPNext uses LDAP, roles are mapped from directory groups at each login under LDAP Settings. Before a directory team renames, moves or deletes a group, check which ERPNext roles it feeds, including System Manager. Test the change in a staging site with a test account, because a mapping that removes roles will apply at the user's next login. Keep the break-glass and named admin accounts outside this mapping so directory changes cannot remove them.

Questions teams ask before recovering ERPNext access

Can we recover ERPNext admin access ourselves without a partner?

Often yes, if you have shell access to the server that runs the site and someone who can run bench commands as the user that owns the bench. The usual route is to reset the Administrator password with the bench --site [sitename] set-admin-password command, then sign in and restore the System Manager role on a named account. The harder cases are when the server is hosted by someone else, when no one on your team has command-line experience, or when the database itself has been changed. In those cases, confirm who controls the host before you start, since that decides who can run the recovery at all.

What drives the effort of an ERPNext lockout recovery?

The main drivers are how you deployed ERPNext, who controls the environment, and how much else changed at the same time. A single-site bench install where your team holds server access is usually a short task. Effort rises when the site runs on a managed platform with no shell access, when several sites share one server, when SSO or LDAP has been configured so that the login path is no longer the local Administrator password, or when role changes have been applied across many users. Each of these adds a step: confirming access, checking the login method, verifying the restored roles and reviewing what the lockout changed.

How long does ERPNext access recovery take?

Measure it in steps rather than days. A typical recovery follows a short sequence: confirm the site and host, reset or verify the Administrator password, sign in, restore a named System Manager account, test the permissions that were changed, and record what happened. The first and last steps usually take the longest in practice, because they depend on people and approvals rather than commands. If you need a firm timeline, ask for the steps and their owners in the written scope, then confirm each one against your own environment.

What access does a partner need to recover ERPNext admin rights?

Partners need only the access required for the agreed steps, and that access should be granted and removed in writing. For a bench-based install, this usually means a named engineer with shell access to the server, the ability to run bench commands as the bench user, and read access to the relevant logs. Database credentials are needed only if the recovery involves database-level checks. Ask for a list of the accounts and hosts involved, the session method used, and confirmation that temporary credentials are rotated after the work. Never share the Administrator password in email or chat.

Does ERPNext support SSO or LDAP logins that could replace the local Administrator?

Yes. ERPNext supports LDAP login against Active Directory or OpenLDAP through LDAP Settings, including SSL/TLS options and automatic mapping of LDAP groups to ERPNext roles at each login. Frappe's Social Login Key feature also lets users sign in through providers such as Google, Microsoft or GitHub, and through custom OAuth or OpenID Connect endpoints. This matters for recovery: if LDAP group mapping removes the System Manager role at login, a lockout can recur on the next sign-in unless the mapping is corrected. Confirm the mapping rules with your identity team before changing roles locally.

How do we prevent another ERPNext lockout?

Keep a break-glass account that is separate from daily administration, store its credentials in a controlled vault, and test that it still works. Before removing System Manager from any user, make sure at least one other named administrator can sign in and manage roles. Record role changes through your normal change process, and restrict who can edit role assignments. Review the account after each upgrade or identity change. These controls reduce risk, but confirm their exact steps for your version and login setup with your team before you rely on them.

When does a fixed-scope engagement make sense for ERPNext access recovery?

A fixed-scope engagement suits recovery work that touches several parts of the system at once, such as a managed host, a multi-site server, an LDAP or SSO login path, or a permissions model that must be rebuilt afterward. DeployOpen works on self-hosted open-source platforms inside your own infrastructure and agrees scope, deliverables and timelines in writing before work starts. Ask for the written steps, the access required, the verification checks and the handover notes. If the work is a one-off reset on a server your team already controls, your own engineers may be enough. If you want ongoing hardening, the same scope can be extended through a retainer.

What should we record after an ERPNext admin lockout?

Record the cause, the steps taken, the accounts changed, the access granted and removed, and the checks that confirmed normal access. Include the ERPNext version, the login method in use and any LDAP or Social Login Key changes. Keep this record with your change and incident process so the next administrator can repeat the recovery safely. Review whether the cause points to a permissions design issue, such as too many users holding System Manager, and plan a fix before the next role change.

How DeployOpen scopes ERPNext access recovery and break-glass design

DeployOpen plans, implements and hardens self-hosted ERPNext inside your own cloud accounts, data centers or air-gapped networks, and recovery from an admin lockout is part of that work, not an afterthought. Before any build starts, we agree in writing which recovery paths your team will rely on, who is allowed to run them, and where the evidence of each use is kept. That scope usually covers the in-app route through another System Manager user, the bench-level route on the server, and a break-glass Administrator account held under a documented custody process. Because most engagements are fixed-scope, these decisions appear in the statement of work with clear deliverables rather than being left to the operations team to work out during an incident.

The design work starts by mapping who holds what. We inventory the users with System Manager, the roles that can edit Role Permissions Manager settings, the shell accounts that can run bench commands on each site, and the systems that federate sign-in, such as LDAP or Social Login Key providers, since an identity outage can lock out the same people as a password problem. We then confirm with you which of these paths survive the failure you are planning for. A break-glass account that depends on the same identity provider it is meant to bypass is a common gap, and we flag it during scoping. Anything about your specific identity provider behavior, or whether your ERPNext version and hosting model expose a given control, should be confirmed with the vendor or with your own test environment before you rely on it.

The written deliverable is a runbook your engineers can follow without DeployOpen present. It sets out the trigger conditions for each recovery path, the approvals required, the exact commands and their expected output, and the post-recovery steps such as rotating the reset credential and reviewing the audit trail. We test the procedure on a non-production site where practical so your team sees it work before it is needed. Ongoing support and periodic re-testing, after upgrades or identity changes, can be added as a retainer. Ask any provider for the quote to itemize the scoping, runbook, test and handover effort separately, and ask who owns the break-glass credential after the engagement ends.

Recovering ERPNext admin access after a lockout