Troubleshooting piveau-ui

This article contains troubleshooting for common errors related to piveau-hub-ui.

Keycloak

TypeError: Cannot read properties of undefined (reading 'BASE_PATH')

This usually occurs because you just came from the migration of vue-cli to Vite for a user-facing web application. We use keycloak-js with silent check-sso configuration. To make silent check-sso work, your application needs to host a dedicated silent-check-sso HTML document (usually silent-check-sso.html). You must point to the right location to this HTML document when initializing keycloak. This location depends on BASE_PATH and how your built-tool handles static HTML documents. If you face this error, consider trying this:

• Ensure that BASE_PATH is defined in all environments. In Vite, you might want to shim process.env.BASE_PATH. Ensure that BASE_PATH points to '/' for OSC and '/data' for production envs. If your web application is not hosted on a path like /data, you may just use / instead
• Ensure that silent-check-sso.html is correctly bundled as a dedicated static asset in the dist directory when built. A common pitfall is that vue-cli uses the public directory and Vite the static directory. So if you migrated from one to the other, ensure to place silent-check-sso.html is in the right directory

TypeError: Cannot read properties of undefined (reading 'loginFn')

That means that for some reason, keycloak-js failed to create a valid keycloak instance. Ensure that

• the version between keycloak client and server match
• a user-config.js file exists

• your user-config.js/runtime-config is set up the right way, especially the keycloak endpoint

  • keycloak v10.x: use keycloak url with /auth path, e.g.,

    https://keycloak.domain.tld/auth

  • later keycloak: do not use /auth path, e.g.,

    https://keycloak.domain.tld

• the Docker container actually applies runtimeconfig. If you migrated from vue-cli to vite, the directory structure of the dist directory changed that causes to break runtimeconfig. To fix this, check runtimeconfig.sh and if your Dockerfile has an actual runtimeconfig script.

• ensure that the pkceMethod is set up correctly to match your keycloak configuration. Either it is deactivated in both keycloak and piveu-ui or it is activated in both. The env variable for that is $VUE_APP_AUTHENTICATION_KEYCLOAK_INIT_PKCE_METHOD, The recommended security setting is to activate PKCE. The following screenshot shows the configuration of keycloak.

Authentication erros from hub repo

If you get access denied answers from hub repo, there could be a number of reasons:

• the user does not have permission to a catalogue. The user has to have edit access to at least one catalogue. This catalogue has to be created first. More on that in the keycloak guide.
• You configured hub repo with a different keycloak domain, than hub ui. E.g. an internal one and an external one. In this case you have to set the issuer in the hub repo configuration. More on that in the keycloak guide.