---
description: Resolve client-side errors in Turnstile widget rendering.
title: Client-side errors
image: https://developers.cloudflare.com/og-docs.png
---
[Skip to content](#main-content)
> Documentation Index
> Fetch the complete documentation index at: https://developers.cloudflare.com/turnstile/llms.txt
> Use this file to discover all available pages before exploring further.
# Client-side errors
Last updated May 5, 2026|Copy as Markdown|[View as Markdown](https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/index.md)|[Agent setup](https://developers.cloudflare.com/agent-setup/)
There are instances where Turnstile may encounter problems, invoking the `error-callback`.
These problems can range from network connectivity issues and browser compatibility problems to configuration errors and challenge failures.
When errors occur, implementing proper error handling ensures your visitors receive helpful feedback and your application can recover from temporary issues.
Refer to the [Error codes](https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/error-codes/) for troubleshooting guidance to address specific error conditions.
## Error handling
The `error-callback` option for explicitly rendering widgets and the `data-error-callback` attribute for implicit rendering provides a JavaScript callback to handle potential errors that occur.
This callback mechanism gives you complete control over how errors are presented to visitors and allows you to implement custom recovery strategies tailored to your application's needs.
```js
turnstile.render('#my-widget', {
sitekey: 'your-sitekey',
'error-callback': function(errorCode) {
console.error('Turnstile error occurred:', errorCode);
handleTurnstileError(errorCode);
return true; // Indicates we handled the error
}
});
```
```html
```
Specifying an error callback is optional, but recommended for production applications. If no error callback is set, Turnstile will throw a JavaScript exception upon error, which can disrupt your page's functionality and create a poor user experience. By providing an error callback, you can catch these exceptions and handle them.
If an error callback returns with a non-falsy result, Turnstile will assume that the error callback handled the error accordingly and will not perform any additional error logging. If the error callback returns with a falsy result (including `undefined`), Turnstile will log a warning to the JavaScript console containing the error code, which can be useful for debugging during development.
An error callback will retrieve an error code as its first parameter. This error code follows a structured format where the first three digits indicate the error family (such as configuration issues, network problems, or challenge failures), and the remaining digits specify the exact error within that family.
```js
function handleTurnstileError(errorCode) {
const errorFamily = Math.floor(errorCode / 1000);
switch(errorFamily) {
case 100:
showMessage('Please refresh the page and try again.');
break;
case 110:
showMessage('Configuration error. Please contact support.');
break;
case 300:
case 600:
showMessage('Security check failed. Please try refreshing or using a different browser.');
break;
default:
showMessage('An unexpected error occurred. Please try again.');
}
}
```
## Retry
By default, Turnstile will automatically retry upon encountering a problem, which helps handle transient network issues or temporary service disruptions without requiring user intervention.
This automatic retry mechanism is useful for [mobile visitors](https://developers.cloudflare.com/turnstile/get-started/mobile-implementation/) who may experience intermittent connectivity or visitors on networks with occasional stability issues.
When subsequent failures due to retries are observed, the error callback can be invoked multiple times for the same underlying issue. Your error handling code should account for this possibility to avoid showing duplicate error messages or performing the same recovery action repeatedly.
```js
let retryCount = 0;
turnstile.render('#my-widget', {
sitekey: 'your-sitekey',
'error-callback': function(errorCode) {
retryCount++;
if (retryCount