Troubleshooting

This page is use to record any issues encountered while configuring, deploying Heimdall, as well as any other development configuration and setup issues.

Below are the some of known issues and how to remediate them.

OpenID Connect/OAuth

Error: Logging in with Keycloak gives an unable to validate state error.

Solution: Enable oAuth compatibility mode "Exclude Session State From Authentication Response".

---

Error: Server is unable to validate session tokens when authenticating with an external provider

Solution: Ensure the Heimdall server is able to communicate with your authentication provider. If you use your own SSL certificates, ensure they are accessible within your Heimdall host (server/container) and specify their path as an environment variable with NODE_EXTRA_CA_CERTS=/path/to/your/certificate.crt

---

Error: User emails are not verified by your identity provider.

Solution: The OpenID Connect Standard provides a field for "email_verified", this is validated to ensure that a user cannot add their own unverified email to your identity provider and use it to login to Heimdall.

Ensure users have the "Email Verified" field enabled:

Setting Up Heimdall Server in Windows

NOTE:

This issue occurs if you are using both Windows and WSL terminals - To avoid the issue entirely, don't mixed terminals while installing or 
running Heimdall. Either use a Windows or WSL terminal for the entire installation process.

After downloading the local copy of the repository and invoking the yarn install the heimdall2\node_modules\@heimdall and the heimdall2\apps\backend\node_modules\@heimdall link directories are not accessible.

PROBLEM: heimdall2\node_modules\@heimdall links not visible/accessible

SOLUTION: Create a Directory Junction hard link using the mklink command.

Step 1: Go to the heimdall2\node_modules\@heimdall folder (use file explore)

Step 2: If the following directories are presented delete them: (cypress-tests, interfaces, and password-complexity)

Step 3: Open a command prompt with admin privileges' in the @heimdall directory

Step 4: Create the hard links as follows:

 mklink /J "cypress-tests" "../../test"
 mklink /J "interfaces" "../../libs/interfaces"
 mklink /J "password-complexity" "../../libs/password-complexity"

PROBLEM: heimdall2\apps\backend\node_modules\@heimdall links not visible/accessible

SOLUTION: Follow the steps listed above to delete the directories (interfaces and password-complexity) and create the links as follows:

 mklink /J "interfaces" "../../../../libs/interfaces"
 mklink /J "password-complexity" "../../../../libs/password-complexity"

NOTE make sure to be in the heimdall2\apps\backend\node_modules\@heimdall before creating the links