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.,
-
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.
Keycloak Server Version and Keycloak Javascript Adapter Version#
piveau-hub-ui uses the Keycloak javascript adapter to communicate with the Keycloak server.
The current version of the javascript adapter is 26.2.0.
There are currently no known issues when upgrading the dependency in piveau-hub-repo to this version. However, this
adapter version seems to require a value in the authentication.keycloakInit.pkceMethod config field, which might not
have been set.
For further guidance on upgrading the adapter you might want to refer to the official migration guide from Keycloak: https://www.keycloak.org/docs/latest/upgrading/#_upgrade_js_adapter
The Keycloak documentation states that
The JavaScript adapter will continue to be backwards compatible with all actively supported releases of the Keycloak server, and deviation from this will be considered a breaking change.
Known compatibilities between server and adapter versions#
| Adapter version | Tested with server version |
|---|---|
| 22.x | 22,23,24 |
| 24.x | 24,25,26 |
| 26.x | 25,26 |