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

Widget Fails to Find the Solution

Problem:

The widget reports “Verification failed,” and the console shows “Unable to find a solution” (with debug enabled).

Solution:

This issue may occur due to:

1. Random Number Exceeds Maximum: Ensure the random number generated by your server does not exceed the configured maximum number. By default, the maximum number is 1,000,000, but it can be overridden by the maxnumber parameter in the challenge response. Align your server’s random number generation with this maximum.

2. Incorrect Challenge Calculation: Verify your server implementation. For details, refer to the server documentation or official libraries for language-specific implementations. For example, check if salt=some_salt?expires=1722614680 and number=1234 generate a SHA-256 challenge equal to 8b1fa4ee51e9e9c8b53cd0c080ca42458accc39424a13fb51e56cfe439814d5f. Ensure any additional parameters (e.g., expires) are included in the hash input.

Secure Context

Problem:

The ALTCHA widget 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 frameworks like Next.js or SvelteKit, 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.

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.