Troubleshooting
At certain stages of CKBox application integration, some problems and issues may arise.
This section seeks to address common application issues and integration obstacles.
# The token URL is missing
CKBox displays the error message: Token URL is missing.
This problem can occur when the token endpoint URL has not been provided for CKBox configuration. CKBox uses JWT tokens for authentication, it is mandatory to supply a valid token endpoint URL for CKBox to work properly.
Read more on how to configure CKBox
# Invalid JWT response from the token endpoint
CKBox displays the error message: Failed to fetch token. Perhaps provided token URL is unreachable.
This problem can occur if the token URL does not respond with the valid JWT token. The URL provided may indeed respond correctly, but its response is not a valid JWT token used by CKBox to authenticate users.
The token endpoint is where the CKBox makes a request to get the token. It should return the token only if the user proves their identity.
Read more on how to configure the token URL.
# Invalid JWT returned from the token callback
CKBox displays the error message: Unable to retrieve a token from the callback.
This problem can occur if callback provided to tokenUrl does not respond with the valid JWT token. It is mandatory to provide a token callback that returns valid JWT tokens for CKBox to work properly.
Read more on how to configure the token URL.
# Invalid token payload
CKBox displays one of the following messages:
Invalid JWT token. Field 'aud' is missing.Invalid JWT token. Field 'sub' is missing.Invalid JWT token. Field 'iat' is missing.Invalid JWT token. Field 'auth.ckbox.role' is missing.
This problem can occur when the token payload is missing one of the information required by CKBox to function correctly.
Read more on how to generate a valid JWT token.
# Malformed token URL
CKBox displays the error message: Token URL seems incorrect.
This indicates that the supplied token URL is malformed, and is not a valid URL. The token URL should be supplied as part of the CKBox configuration.
Read more on how to start with the CKBox
The token endpoint is unreachable
CKBox displays the error message: Failed to fetch token. Response code: 500. Such an error indicates that the token endpoint configured in the tokenUrl has stopped responding correctly. This could mean a temporary downtime on that endpoint or a more serious server error.
# Malformed serviceOrigin URL
CKBox displays the error message: Malformed serviceOrigin URL.
This problem can occur if the service URL passed to the configuration is not a valid URL. This option should be set only if you host the CKBox backend on your own. It should not be present if you use CKBox in the SaaS version.
Read more on how to configure CKBox integration.