# Troubleshooting

This page provides guidance for resolving common issues related to ALTCHA integrations. To begin, enable debug mode on the widget and check the logs in the developer console.

## Debug Mode

To enable debug mode on the [widget](/docs/integration/widget/), use the `debug` attribute:

```html
<altcha-widget
debug
></altcha-widget>
```

Debug mode will output log messages to the console. Open your browser’s developer console to view these logs.

## Common Issues

### Secure Context

_Problem:_ 

The ALTCHA widget or show an error **Secure context (HTTPS) required.** or fails with the following error in the developer console:  
`Uncaught TypeError: Cannot read properties of undefined (reading 'digest')`.

_Solution:_  

The ALTCHA widget relies on the browser's built-in [SubtleCrypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) interface for secure cryptographic operations. This interface is only available in a [secure context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts), which typically requires HTTPS or certain localhost configurations.

To resolve this issue:  
1. Ensure your website is accessed over HTTPS.  
2. For local development, use supported localhost domains, such as:  
- `http://localhost`  
- `http://*.localhost` (e.g., `http://myapp.localhost`)  

This will enable the secure context required for the widget to function properly.

### Event Listeners Don’t Work

_Problem:_

Events such as `statechange` or `verified` are not triggered.

_Solution:_

Ensure you attach event listeners after the ALTCHA script has loaded and the component is initialized.

1. **Attach Listeners After Initialization:**  
Event listeners must be added only after the ALTCHA script has fully loaded and the component is initialized.  

- **For Modern Frameworks and Bundlers:**  
 Ensure that you `import 'altcha'` into your application.  

- **For Custom JavaScript:**  
 Use the `DOMContentLoaded` event to attach listeners:  
 ```javascript
 document.addEventListener('DOMContentLoaded', () => {
   altchaWidgetElement.addEventListener('statechange', (event) => {
     // Handle statechange event
   });
 });
 ```  

2. **Handling Asynchronous Imports:**  
If using asynchronous imports, such as `import('altcha')`, wait for the import to resolve before adding listeners:  
```javascript
import('altcha').then(() => {
 altchaWidgetElement.addEventListener('statechange', (event) => {
   // Handle statechange event
 });
});
```  

### Content Security Policy (CSP) Issues

_Problem:_

The widget doesn’t render properly, or the console shows CSP-related errors.

_Solution:_

Consult the [Content Security Policy documentation](/docs/integration/widget/#content-security-policy-csp) to configure CSP properly for the widget.

### Cross-Origin Resource Sharing (CORS) Issues

_Problem:_

The widget fails to fetch the challenge from the server, and CORS-related errors appear in the console.

_Solution:_

This issue arises when your website or application is on a different domain than your server. Enable CORS (Cross-Origin Resource Sharing) on your server. A basic CORS configuration includes:

```
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
```

For detailed guidance, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#the_http_response_headers).