Reset an Uptime Kuma password with the installation’s bundled command-line utility. For Docker, stop the container and run docker exec -it <container name> npm run reset-password. For a non-Docker installation, stop Uptime Kuma, change to its installation directory, and run npm run reset-password. The interactive utility asks for the account and a new password, then you restart Uptime Kuma and sign in. Password recovery and two-factor-authentication removal are separate operations.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
The supported way to reset an Uptime Kuma password
Uptime Kuma does not require a default password or manual edits to its SQLite database for this recovery. The supported path is the reset-password npm script shipped with Uptime Kuma. It works from the deployment that owns the live data: inside the relevant Docker container for a containerized setup, or from the Uptime Kuma installation directory for a direct installation.
As an Amazon Associate I earn from qualifying purchases.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesThe command is intentionally the same across release generations:
npm run reset-passwordDocker adds the container-execution wrapper:
docker exec -it <container name> npm run reset-passwordKeep Uptime Kuma stopped while running the utility. A running server can keep the database connection pool busy or continue listening on port 3001, producing a timeout, an EADDRINUSE error, or a reset that appears to complete without changing the password.
Choose the procedure for your deployment
| Deployment | Where the command runs | Access you need | Command |
|---|---|---|---|
| Docker | Inside the Uptime Kuma container | Permission to list, stop, and execute commands in the container | docker exec -it <container name> npm run reset-password |
| Non-Docker | The host directory containing Uptime Kuma | Shell access and permission to run the installation’s Node/npm commands | npm run reset-password |
| Lost authenticator code | The same deployment location as above | Administrative shell access | Run the separate remove-2fa script, then reset the password if needed |
The final result is the same: the account’s password is changed by Uptime Kuma’s own administrative code rather than by manipulating database rows.
Before you start
Confirm which installation owns the data
A host may contain more than one Uptime Kuma deployment, an old container, or several data directories. Resetting the wrong instance changes a different account and leaves the login you are trying to use unchanged. If Uptime Kuma runs in Docker, identify the active container first:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutedocker psUse the container name shown for the running Uptime Kuma instance. If you use a compose project, the generated name may differ from the service name in your compose file; copy the name displayed by docker ps.
For a direct installation, locate the directory in which Uptime Kuma was installed. It is the directory containing the project’s package.json and the application files. Run the reset command from that directory, not from an unrelated shell location.
Arrange a maintenance window
Stop the normal Uptime Kuma process or container before invoking the reset utility. Monitoring will be unavailable while the service is stopped, so notify anyone who relies on its alerts. Do not start a second copy merely to run the reset; two processes competing for the same database can create the exact connection and port conflicts this procedure is intended to avoid.
Have the account name ready
The utility is interactive. You will be prompted to identify the Uptime Kuma username and to enter and confirm a new password. The password is not supplied as a command-line argument, so it will not appear in shell history. Use the exact username configured in Uptime Kuma.
Docker: step-by-step password reset
1. Find the running container
On the Docker host, run:
docker psRead the NAMES column and note the Uptime Kuma container name. If several containers look similar, verify the image, ports, and deployment directory before continuing. The reset must run against the container that has the data volume used by the service you normally open in your browser.
2. Stop Uptime Kuma
Stop the identified container using your normal Docker administration method. With the name from docker ps, the direct command is:
docker stop <container name>Wait for Docker to report that the container has stopped. If a compose or orchestration tool automatically restarts it, temporarily disable that restart behavior or stop the service through the same tool; otherwise the server may come back before the reset starts.
3. Run the bundled utility
Invoke the npm script through Docker:
docker exec -it <container name> npm run reset-passwordThe command must target a running container, so a stopped container may need to be started briefly in a way that does not launch the normal Uptime Kuma server, depending on the image and entrypoint. Follow the image’s documented administrative procedure if your container exits immediately when stopped. The essential requirement is that the reset utility runs against the same mounted data used by the service and that no normal server process is competing for the database or port.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →4. Answer the prompts
Enter the requested username, type a new password, and enter it again when prompted. The utility performs the account update using Uptime Kuma’s application logic. Do not close the terminal until it reports completion or returns an error.
5. Start the container and test
Start the container with the same Docker or compose command you ordinarily use. Open the Uptime Kuma sign-in page and test the changed password. If the browser retained an old session or autofill value, type the new password manually or use a private window to avoid confusing a stale credential with a failed reset.
Non-Docker installation: step-by-step
1. Stop the service or process
Stop Uptime Kuma with the service manager, process supervisor, or shell procedure used for your installation. The exact stop command varies by operating system and supervisor; the important condition is that the Uptime Kuma server is no longer running and is not listening on its normal port.
2. Change to the installation directory
Open a shell and change into the directory that contains the Uptime Kuma project files and package.json. Confirm that the directory is the installation associated with the data you need to recover.
Recommended Free Tools
3. Run the reset script
npm run reset-passwordIf your shell reports that npm or Node.js is unavailable, use the same Node.js environment and account that normally starts Uptime Kuma. Do not substitute a globally installed package or run the command from a different checkout; the script must operate on the intended installation and database.
4. Complete the interactive prompts
Provide the username and new password when requested, including the confirmation entry. Keep the terminal open until the script exits. A clean return does not by itself prove that you targeted the correct data directory, so verify the login after restarting.
5. Restart and sign in
Start Uptime Kuma using your normal service command. Sign in with the new password and check that your monitors and settings are present. Seeing the expected monitors is a practical confirmation that you reset the account in the correct installation rather than an empty or obsolete copy.
When the problem is two-factor authentication, not the password
A forgotten authenticator code is a different lockout from a forgotten password. Current Uptime Kuma package metadata defines a separate administrative script for removing two-factor authentication. Run that script from the same deployment location used for the password utility:
npm run remove-2faFor Docker, execute it through the container in the same way as the password script:
docker exec -it <container name> npm run remove-2faStop the normal Uptime Kuma server first, then follow the script’s prompts. Removing 2FA does not inherently change the account password. If you also forgot the password, run reset-password as a separate operation and restart the service before testing both credentials.
Troubleshooting reset-password failures
Knex timeout or database connection acquisition failure
A Knex timeout means the utility could not obtain a usable database connection. The first remedy is operational, not a database edit:
- Stop the normal Uptime Kuma process or container completely.
- Check that an automatic restart policy has not started it again.
- Run the reset command from the correct container or installation directory.
- After the utility exits, restart Uptime Kuma and test the new password.
An upstream issue documents this class of failure when the database connection pool was unavailable. Retrying while the server is still running usually reproduces the problem.
EADDRINUSE on port 3001
EADDRINUSE indicates that another process already owns the port Uptime Kuma is trying to bind, commonly port 3001. Stop the normal server before running administrative commands. If the error persists, identify and stop the remaining Uptime Kuma process or container, then retry. Do not change the port merely to disguise the conflict; the goal is to run the utility against the existing data without a second server instance.
The command appears to finish, but the old password still fails
Check these items in order:
- Container identity: confirm that the command used the container serving your browser session, not an old or similarly named container.
- Data location: verify that the container or host directory contains the live Uptime Kuma data volume.
- Restart: restart the service after the script exits so the application reloads the updated account data.
- Username: make sure the prompt was answered with the intended Uptime Kuma username.
- Browser state: enter the new password manually or test in a private window to rule out stale autofill.
If the expected monitors and settings are missing after login, stop and recheck the deployment and data directory rather than resetting accounts repeatedly.
The container cannot be used with docker exec
docker exec requires a running container. Some deployments stop the container immediately when their normal server process is stopped. In that case, use the container image’s documented administrative or compose procedure to start the container in a way that permits the bundled npm script to run against the mounted data, while ensuring that a second normal server is not competing for the database or port. Do not create a new container without the original data volume: that would reset or create an account in a different data store.
Node or npm version errors
Runtime requirements depend on the Uptime Kuma release you installed. Current upstream master package metadata reports version 3.0.0-beta.0 and a requirement of Node.js >= 26.2.0; those are branch-state facts and can change. They are not universal requirements for every stable release. Use the Node.js version supported by your installed Uptime Kuma release and invoke the npm script supplied with that release. Avoid replacing the project files with a newer checkout solely to obtain a reset command, because that can introduce an unintended upgrade.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Why the npm command is preferable to internal filenames
The stable user-facing interface is npm run reset-password. In current upstream master, that script invokes node --import=tsx extra/reset-password.mts. Older releases used a JavaScript implementation behind the same npm command. The internal filename and runtime can therefore change while the npm script remains the documented entry point.
For that reason, do not hard-code extra/reset-password.mts into an operational runbook unless you have verified that exact file in the release you are running. The npm script lets each release select its own implementation and dependencies.
Operational and security checks after recovery
Confirm the account and application state
- Sign in with the new password after a full service restart.
- Verify that the expected monitors, notification settings, and history are visible.
- Confirm that the browser is pointed at the intended host and port.
- If you removed 2FA, re-enroll an authenticator after access is restored and store recovery information securely.
Protect the reset session
Run the utility from an administrator shell on the host that owns the Uptime Kuma data. Treat terminal access as equivalent to administrative access to the monitoring installation. Do not paste the new password into shell arguments, scripts, tickets, or chat logs. The interactive prompt avoids putting the password in the command itself.
Do not edit the database manually as a first resort
Direct SQLite edits can corrupt account data, mishandle password hashing, or affect the wrong database file. The bundled scripts are the supported recovery mechanism and should be exhausted before considering any manual intervention. If you have an unusual failure that requires database recovery, make a tested backup and use a recovery plan appropriate to your release rather than copying an unverified SQL statement.
Quick Recap
Quick recovery checklist
- Determine whether the installation is Docker-based or direct.
- Identify the active container name with
docker ps, or locate the correct non-Docker installation directory. - Stop the normal Uptime Kuma process or container.
- Run
docker exec -it <container name> npm run reset-passwordfor Docker, ornpm run reset-passwordin the installation directory for a direct install. - Enter the username and new password at the prompts.
- If the lockout is an authenticator-code problem, run the separate
remove-2fascript; reset the password separately if necessary. - Restart Uptime Kuma and sign in.
- If it fails, resolve port or database-connection errors first, then verify the container and data directory before retrying.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
