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, use the debug attribute:

<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 interface for secure cryptographic operations. This interface is only available in a secure context, 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:

     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:

   import('altcha').then(() => {
     altchaWidgetElement.addEventListener('statechange', (event) => {
       // Handle statechange event
     });
   });

Server-Side Rendering (SSR) Issues

Problem:

When using certain server-render frameworks, the build may fail with the error ReferenceError: customElements is not defined.

Solution:

The ALTCHA widget is a custom WebComponent and depends on the Window.customElements property, which is not typically available in SSR environments.

To resolve this, ensure that the widget is only imported on the client (browser). For example, use the dynamic import('altcha') function. Some frameworks offer helper functions to detect whether the code is running on the server. If not, you can manually check the browser environment by verifying typeof window.

For example, in SvelteKit, you can use $app/environment to detect if the code is running in the browser:

+page.svelte

<script>
  import { browser } from '$app/environment';

  if (browser) {
    import('altcha');
  }
</script>

<altcha-widget></altcha-widget>

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