The sections below deal with recovering from a situation where you are not able to sign in, or need to recover your data.
If you’ve forgotten your username, ask the owner to help you. If you are the owner and have forgotten your user name, then you need to prepare the system to start a new onboarding process.
If you are not the owner or do not have administrator rights, ask the owner to give you a new password.
- In the navigation pane on the left, check if you see the Settings menu listed above the Notifications.
- If you don’t, you do not have administrator rights.
If you are the owner or have administrator, there are different methods to reset a password, depending on your setup:
The method used to reset a password depends on your user rights:
- If you are a regular user without administrator rights, ask the owner to give you a new password.
- If you are the owner, choose one of the procedures below to reset your password.
- You cannot recover an owner password from within Home Assistant.
- There is only one owner per system. You cannot add a new owner.
- If you are an administrator, add a new user as an administrator and give the new user a password you can remember.
- Then log out, and log in with this new user.
- Reset your password via this new administrator account (and then delete this new account).
- Your configuration will remain, and you don’t have to do a new onboarding process.
Use this procedure only if the following conditions are met:
- You know the username.
- You can access the Home Assistant console on the device itself (not via the SSH terminal from the add-ons).
- Connect to the console of the Home Assistant server:
- If you are using a virtual machine, connect to your virtual machine console.
- If you are using a Home Assistant Yellow, refer to the following procedure:
- If you are using a Home Assistant Green, refer to the following procedure:
- If you are using another board, connect a keyboard and monitor to your device and access the terminal. The procedure is likely very similar to the one described for the Green in the step above.
- Once you have opened the Home Assistant command line, enter the following command:
existing_useris a placeholder. Replace it with your user name.
new_passwordis a placeholder. Replace it with your new password.
auth reset --username existing_user --password new_password
Troubleshooting: If you see the message
zsh: command not found: auth, you likely did not enter the command in the serial console connected to the device itself, but in the terminal within Home Assistant.
- You can now log in to Home Assistant using this new password.
If you are running Home Assistant in a container, you can use the command line in the container with the
hass command to change your password. The steps below refer to a Home Assistant container in Docker named
homeassistant. Note that while working in the container, commands will take a few moments to execute.
docker exec -it homeassistant bashto open to the container command line
hassto create a default user, if this is your first time using the tool
hass --script auth --config /config change_password existing_user new_passwordto change the password
exitto exit the container command line
docker restart homeassistantto restart the container.
Only the owner can change other user’s passwords.
- In the bottom left, select your user to go to the Profile page and make sure Advanced Mode is activated.
- Go to Settings > People and select the person for which you want to change the password.
- At the bottom of the dialog box, select Change Password.
- Note: this is available as the owner, not administrator.
- Enter the new password, and select OK.
- Confirm the new password by entering it again, and select OK again.
- A confirmation box will be displayed with the text Password was changed successfully.
You need to be an owner or have administrator rights to delete a user.
- Go to Settings > People and select the person which you want to delete.
- Note: you cannot delete the owner.
- At the bottom of the dialog box, select Delete.
- A confirmation dialog box will be displayed.
- To confirm, select OK.
If you lose the password associated with the owner account and the steps above do not work to reset the password, the only way to resolve this is to start a new onboarding process.
If you have an external backup with an administrator account of which you still know the login credentials, you can restore that backup.
If you do not have a backup, resetting the device will erase all data.
If you have a Home Assistant Green, reset the Green.
If you have a Home Assistant Yellow, reset the Yellow.
Unless your SD card/data is corrupted, you can still get to your files or troubleshoot further. There are a few routes:
- Connect a USB keyboard and HDMI monitor directly to the Raspberry Pi.
- Remove the SD and access the files from another machine (preferably one running Linux).
If you’re using a Raspberry Pi, you’re likely going to have to pull the power in order to get your monitor recognized at boot. Pulling power has a risk of corrupting the SD, but you may not have another option. Most standard USB keyboards should be recognized easily.
Once you’re connected, you’ll see a running dmesg log. Hit the enter key to interrupt the log. Sign in as “root”. There is no password.
You will then be at the Home Assistant CLI, where you can run the custom commands. These are the same as you would run using the SSH add-on but without using
ha in front of it. For example:
core logsfor Home Assistant Core log
supervisor logsfor supervisor logs
host rebootto reboot the host
dns logsfor checking DNS
- etc (typing
helpwill show more)
The files are on an EXT4 partition (
hassos-data) and the path is
These are easily accessed using another Linux machine with EXT support.
For Windows or macOS you will need third party software. Below are some options.
- Windows: https://www.diskinternals.com/linux-reader/ (read-only access to the SD)
- macOS: https://osxfuse.github.io/