# 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.

<a id="the-token-url-is-missing">

## 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](../guides/configuration/configuration-options.md)

<a id="invalid-jwt-response-from-the-token-endpoint">

## 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.](../guides/configuration/configuration-options.md#tokenurl)

<a id="invalid-jwt-returned-from-the-token-callback">

## 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.](../guides/configuration/configuration-options.md#tokenurl)

<a id="invalid-token-payload">

## 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.](../guides/configuration/authentication.md#token-payload)

<a id="malformed-token-url">

## 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](../guides/quick-start.md)\
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`](../guides/configuration/configuration-options.md#tokenurl) has stopped responding correctly. This could mean a temporary downtime on that endpoint or a more serious server error.

<a id="malformed-serviceorigin-url">

## 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.](../guides/configuration/configuration-options.md#serviceorigin)

---

Full index of the CKBox documentation: [llms.txt](../../llms.txt)