# Uploader Widget Troubleshooting

This guide provides best practices and troubleshooting tips for the CKBox Uploader Widget to help you resolve common issues.

<a id="error-state-display">

## Error State Display

The uploader widget is designed to handle errors and display them to users. When an error occurs:

* The widget will automatically display an error state with a user-friendly message.
* Users will see a clear indication that something went wrong.
* The error dialog will show the error type and a compact message when available.

<a id="debugging-with-developer-tools">

## Debugging with Developer Tools

For detailed error information and debugging:

1. **Open Developer Tools**: Press `F12` to open your browser’s debugging tools.
2. **Check Console**: Look in the Console tab for detailed error messages.
3. **Network Tab**: Check network requests to identify authentication or API issues.

The developer tools will provide more detailed information than what is displayed in the user interface, making it easier to diagnose and resolve issues.

<a id="common-error-scenarios">

## Common Error Scenarios

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

### Invalid Token URL

**Symptoms:**

* Widget displays error state.
* Console shows authentication errors.
* Network requests return 401/403 status codes.

**Solutions:**

* Verify the `tokenUrl` parameter is correctly set.
* Ensure the token endpoint is accessible and returns valid tokens.
* Check that the token URL is using the correct protocol (`https://`).
* Verify the token endpoint is not blocked by CORS policies.

```javascript
// Correct token URL format
CKBoxWidget.mountUploaderWidget(document.getElementById('ckbox'), {
	tokenUrl: 'https://your-domain.com/api/ckbox/token'
});
```

<a id="invalid-workspace-id">

### Invalid Workspace ID

**Symptoms:**

* Widget fails to load or shows error state.
* Network requests return 404/403 status codes.

**Solutions:**

* Verify the `workspaceId` parameter matches your CKBox workspace.
* Check that the workspace ID is properly formatted.
* Ensure the workspace exists and is accessible with your token.
* Verify the workspace ID is not empty or undefined.

```javascript
// Correct workspace ID usage
CKBoxWidget.mountUploaderWidget(document.getElementById('ckbox'), {
	tokenUrl: 'https://your-domain.com/api/ckbox/token',
	workspaceId: 'your-workspace-id-here'
});
```

<a id="authentication-failures">

### Authentication Failures

**Symptoms:**

* Widget shows authentication error.
* Console shows 401 Unauthorized errors.
* Token refresh failures.

**Solutions:**

* Verify token endpoint returns valid JWT tokens.
* Check token expiration and refresh logic.
* Ensure proper authentication headers.
* Verify token has necessary permissions for the workspace.

---

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