Troubleshooting

The first step in troubleshooting is to take a look at the logs.

• In the UI, go to Settings > System > Logs.

  

For a description of your installation environment:

• go to Settings > System > Repairs > Three dots in the upper right > System information.

About multi-factor authentication

Multi-factor authentication uses a combination of two or three different ways to authenticate your identity:

1. Something you know (like a password).
2. Something you have (like a code generated by a device or service only you have access to).
3. Who you are (indicated by some biometric such as a fingerprint).

If you enable multi-factor authentication for KS Assistant Cloud, in addition to your password, you will be asked for a code from a multi-factor authentication application such as Google Authenticator.

This page shows you how to enable multi-factor authentication (MFA) for KS Assistant Cloud, and how to disable it again later.

Enabling multi-factor authentication (MFA) for KS Assistant Cloud

Step-by-step instructions on enabling multi-factor authentication (MFA) to log in to your KS Assistant Cloud account.

Prerequisites

• A KS Assistant Cloud account
• KS Assistant version 2025.1.0 or later
  • If you're unsure what version you're running, in KS Assistant, open Settings > About.
  • If you are running an older version, and have MFA enabled on KS Assistant Cloud, you won't be able to log into Cloud from KS Assistant. You will need to update KS Assistant first.
• Administrator rights in KS Assistant
• A multi-factor authentication application. For example:
  • A dedicated authenticator app on your phone, such as
    • Google Authenticator
    • Microsoft Authenticator
  • A password manager with authenticator capabilities, such as
    • 1Password
    • If you are using a password manager for this, make sure you have added an entry for your KS Assistant Cloud account.
    • Then, add a section in that entry for one-time password (OTP)

To enable multi-factor authentication (MFA) for KS Assistant Cloud

1. On the Kingsignal account page, log into your account.
2. Under Manage account -> Multi-factor authentication, select Enable MFA.
   • Result: A QR code and a setup code are displayed.
3. To add KS Assistant Cloud to your authenticator app, follow the instructions on screen:
   1. Open your authenticator app.
   2. In the app, either scan the QR code or copy and paste the code manually into the authenticator app.
      • If you are not using a dedicated authenticator app but a password manager, in the entry for the KS Assistant Cloud login, enter a section for one-time password and enter the code there.
      • Result: The app generates a one-time code.
4. On the Kingsignal website, enter the code.
   • Result: Multi-factor authentication is enabled.
   • From now on, you need the authenticator app to generate a code every time you log into KS Assistant Cloud.

Disabling multi-factor authentication (MFA) for KS Assistant Cloud

Follow these steps to disable multi-factor authentication (MFA) for your KS Assistant Cloud account.

Prerequisites

• Have multi-factor authentication (MFA) enabled for KS Assistant Cloud
• Have access to the multi-factor authentication application you used to set MFA up

To disable multi-factor authentication (MFA) for KS Assistant Cloud

1. Log into your KS Assistant Cloud account.
2. Under Manage account > Multi-factor authentication, select Disable MFA.
   • Result: Multi-factor authentication is disabled.
   • When logging into KS Assistant Cloud, you will no longer be prompted to provide a one-time code.

Troubleshooting

I lost the device that I use to generate the MFA token

Symptom

You have multi-factor authentication enabled to log in to KS Assistant Cloud. Now, you lost the device that is used to generate the multi-factor authentication token. For example, you lost the phone that has the authenticator app installed.

Resolution

Submit a ticket to our Customer Support team.

Related topics

• Ente Auth
• Google Authenticator
• Microsoft Authenticator
• 1Password

If you are using Cloudflare for DNS, make sure the records do not have proxy enabled for the DNS records.

You can use a tool like dnschecker.org to see if the DNS records has the expected values.

Condition

Under System > KS Assistant Cloud, Remote connection, you see the following message: Remote control is being prepared. We will notify you when it's ready.

Description

This message indicates that there is an issue generating the SSL certificate that is used to create an encrypted connection between your KS Assistant instance and Nabu Casa Cloud.

Remedy

Depending on what is causing this issue, there are different steps you can try to resolve this.

1. Wait for 5 minutes. It may take a while to generate the certificate.
2. Check if there is a general network issue.

If none of the above applies, check if there is an IPv6 issue.

1. To check the IPv6 connection, in your browser, open test-ipv6.com.

   • Try the steps suggested by the website.

2. If the IPv6 test revealed that there is an IPv6 issue, and if you are not running KS Assistant on a VM, try disabling IPv6:

   • In the UI, go to System > Network.
   • Under Configure network interfaces, expand the IPv6 dropdown.
   • Choose the disabled option and save the changes.
   • To have all network settings applied from scratch, reboot the host. Select Settings > System > Restart KS Assistant (top right) > Expand Advanced Options > Reboot system.

If the problem persists, try resetting your KS Assistant Cloud data and requesting a new certificate:

1. Open Settings > KS Assistant Cloud.
2. Select the three dots menu (⋮) in the upper-right corner.
3. Select Reset cloud data.
4. Restart KS Assistant:
   • Go to Settings > System > Restart KS Assistant (top right).
   • Select Reboot system.
5. Once KS Assistant restarts, go back to the KS Assistant Cloud page and sign in with your Kingsignal credentials.
6. Wait a few minutes while KS Assistant attempts to request and download a new SSL certificate for your remote URL.

If resetting cloud data did not resolve the issue, do not reset it again and instead contact Kingsignal support.

Symptom

When trying to access the KS Assistant user interface, you see the message:

• You're about to give https://somekey.ui.nabu.casa/ access to your KS Assistant instance. Logging in with Trusted Networks. Login aborted: Your computer is not allowed.

Cause

This message indicates that you have trusted networks configured in the configuration.yaml file. Due to the way the Remote UI is set up, you cannot use trusted_networks over the cloud URL.

Resolution

There's two ways to resolve this. Option 1 is to not use trusted networks at all. Option 2 is to use trusted networks, but only locally.

Option 1: Do not use trusted_networks

1. Open your configuration.yaml file.

2. Delete the entire type: trusted_networks section.

   homeassistant:
   auth_providers:
      - type: trusted_networks
        trusted_networks:
         - 192.168.0.0/24

3. If you like, set up Multi-factor authentication.

4. To apply the new network settings, restart KS Assistant.

5. Log in with your credentials and multi-factor authentication.

Option 2: Keep using trusted_networks, but only locally

1. Open your configuration.yaml file.

2. Make sure that in addition to type: trusted_networks, you also have a type: homeassistant section.

   homeassistant:
   auth_providers:
      - type: homeassistant
      - type: trusted_networks
        trusted_networks:
         - 192.168.0.0/24

3. If you like, set up multi-factor authentication.

4. To apply the new network settings, restart KS Assistant.

5. In the login screen, choose KS Assistant Local.

   • Log in with your credentials and multi-factor authentication.

Symptom

One of your KS Assistant users cannot access KS Assistant remotely.

Cause

This indicates that this user is restricted to local access.

Resolution

To allow people to access KS Assistant remotely, perform the following steps:

1. Go to Settings > People.
2. Select the user.
3. Enable Allow person to login.
4. Make sure the Can only log in from the local network option is disabled.

Symptom

You are using the Remote UI feature. Instead of the KS Assistant user interface, the browser shows a 403 Forbidden message.

Cause

403 Forbidden indicates that IP banning has been configured in your configuration.yaml file and that the ban has been triggered.

# Example configuration.yaml entry
http:
  trusted_proxies:
    - 10.0.0.200
    - 172.30.33.0/24
  ip_ban_enabled: true
  login_attempts_threshold: 5

Resolution

1. Open your configuration.yaml file.

2. If ip_ban_enabled is set to true:

   • In the configuration folder, you should see an ip_bans.yaml file.

   • In the ip_bans.yaml file, delete the 127.0.0.1 entry.

     127.0.0.1:
       banned_at: "2023-07-17T14:20:03"

3. To apply the changes, save the ip_bans.yaml file and restart KS Assistant.

Symptom

Under System > KS Assistant Cloud:

• The Cloud connection status is Connecting…
• You see a message Unable to connect.

Cause

This error indicates a network issue. It often occurs when the KS Assistant host has a bad IPv6 network configuration. Fixing the network configuration or disabling IPv6 on the host should resolve this error.

Resolution

1. To check the IPv6 connection, in your browser, open test-ipv6.com.
   • Try the steps suggested by the website.
2. If there is an IPv6 issue and the step above didn't work: try disabling IPv6:
   • In the UI, go to System > Network.
   • Under Configure network interfaces, expand the IPv6 dropdown.
   • Choose the disabled option and save the changes.
   • To have all network settings applied from scratch, reboot the host. Select Settings > System > Restart KS Assistant (top right) > Reboot system.

Calling a webhook URL can return various status codes for different problems. Below is a list of the most common codes and reasons.

Code	Description
404	The webhook URL you tried is not valid. Visit the Cloud panel to verify the URL you are using.
405	The method (GET/POST/etc.) used for the webhook is not allowed. Check the trigger configuration of your automation to make sure you are calling it correctly.
503	Your KS Assistant instance is not connected properly to our services. Check your system health section.