How to fix captcha_failed: Captcha verification process failed in Supabase

What this error means

When Supabase receives an authentication request with CAPTCHA protection enabled, it verifies the CAPTCHA token against your configured provider (hCaptcha or Cloudflare Turnstile). This error occurs when the verification fails, which usually means either the token is missing from the request, the token has already been used or expired, or the CAPTCHA provider's secret key in Supabase is incorrect. The Supabase auth service cannot verify that a human completed the CAPTCHA challenge, so it blocks the authentication request to prevent bot abuse.

Typical symptoms

• Sign-up or sign-in requests fail with "captcha_failed" error message
• Users can see the CAPTCHA widget but still get verification errors
• OAuth login fails after CAPTCHA is enabled in Supabase Auth settings
• Local testing works with dummy keys but fails in production
• The same credentials work in one environment but fail in another
• CAPTCHA errors occur intermittently, especially with rapid requests

Common causes

1. CAPTCHA token is not being passed to the Supabase auth function (missing captchaToken in options)
2. The captchaToken variable is undefined or in the wrong scope in your application code
3. CAPTCHA token has expired (tokens typically expire after 5 minutes)
4. The same CAPTCHA token is being reused for multiple authentication attempts
5. Supabase CAPTCHA Secret key is incorrect or does not match the provider's key
6. CAPTCHA provider (hCaptcha or Turnstile) site key and secret key mismatch
7. OAuth login attempts do not include CAPTCHA verification in the auth flow
8. Local testing using localhost without proper domain configuration (ngrok not set up)
9. CAPTCHA widget was not reset after a previous use, preventing new token generation

How to fix "captcha_failed: Captcha verification process failed"

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(url, key);

// In your sign-up handler
const { data, error } = await supabase.auth.signUp({
  email: userEmail,
  password: userPassword,
  options: {
    captchaToken: captchaToken // ← Make sure this is included
  }
});

// Or for sign-in
const { data, error } = await supabase.auth.signInWithPassword({
  email: userEmail,
  password: userPassword,
  options: {
    captchaToken: captchaToken // ← Must be passed here too
  }
});

const { data, error } = await supabase.auth.signInAnonymously({
  options: {
    captchaToken: captchaToken
  }
});

import HCaptcha from '@hcaptcha/react-hcaptcha';
import { useRef, useState } from 'react';

function SignUpForm() {
  const captchaRef = useRef(null);
  const [captchaToken, setCaptchaToken] = useState<string | null>(null);

  const handleCaptchaVerify = (token: string) => {
    setCaptchaToken(token);
  };

  const handleSignUp = async () => {
    if (!captchaToken) {
      alert('Please complete the CAPTCHA');
      return;
    }

    const { data, error } = await supabase.auth.signUp({
      email: email,
      password: password,
      options: {
        captchaToken: captchaToken
      }
    });
  };

  return (
    <>
      <HCaptcha
        ref={captchaRef}
        sitekey="your-site-key"
        onVerify={handleCaptchaVerify}
      />
      <button onClick={handleSignUp}>Sign Up</button>
    </>
  );
}

import { Turnstile } from '@captcha/react';
import { useState } from 'react';

function SignUpForm() {
  const [captchaToken, setCaptchaToken] = useState<string | null>(null);

  return (
    <>
      <Turnstile
        sitekey="your-turnstile-site-key"
        onVerify={(token: string) => setCaptchaToken(token)}
      />
      <button onClick={() => handleSignUp(captchaToken)}>Sign Up</button>
    </>
  );
}

// ❌ WRONG: captchaToken declared in wrong scope
function SignUpForm() {
  let captchaToken; // Declared here

  function handleCaptchaVerify(token: string) {
    const captchaToken = token; // Redeclared in nested scope!
    // This only sets the local variable, not the outer one
  }

  function handleSubmit() {
    console.log(captchaToken); // Still undefined!
  }
}

// ✓ CORRECT: Use the same variable
function SignUpForm() {
  let captchaToken; // Declared once

  function handleCaptchaVerify(token: string) {
    captchaToken = token; // Assign to outer variable
  }

  function handleSubmit() {
    console.log(captchaToken); // Now has the token
  }
}

const [captchaToken, setCaptchaToken] = useState<string | null>(null);

const handleCaptchaVerify = (token: string) => {
  setCaptchaToken(token); // Updates state for all components
};

const captchaRef = useRef(null);

const resetCaptcha = () => {
  captchaRef.current?.resetCaptcha();
};

const handleSignUp = async () => {
  try {
    const { error } = await supabase.auth.signUp({
      email, password,
      options: { captchaToken }
    });
    if (error) {
      resetCaptcha(); // Reset for retry
      setCaptchaToken(null);
    }
  } catch (err) {
    resetCaptcha();
  }
};

ngrok http 3000

sudo nano /etc/hosts
   # Add line:
   # 127.0.0.1 yourdomain.local

Advanced notes

Frequently asked questions

What does "captcha_failed: Captcha verification process failed" mean?

When Supabase receives an authentication request with CAPTCHA protection enabled, it verifies the CAPTCHA token against your configured provider (hCaptcha or Cloudflare Turnstile). This error occurs when the verification fails, which usually means either the token is missing from the request, the token has already been used or expired, or the CAPTCHA provider's secret key in Supabase is incorrect. The Supabase auth service cannot verify that a human completed the CAPTCHA challenge, so it blocks the authentication request to prevent bot abuse.

How do I fix "captcha_failed: Captcha verification process failed"?

The CAPTCHA verification failed during Supabase authentication, typically because the CAPTCHA token was not passed correctly to the auth request or the token has expired. Ensure your frontend is passing the captchaToken in the options parameter and that your Supabase CAPTCHA provider keys are correctly configured.

What causes "captcha_failed: Captcha verification process failed"?

CAPTCHA token is not being passed to the Supabase auth function (missing captchaToken in options) The captchaToken variable is undefined or in the wrong scope in your application code CAPTCHA token has expired (tokens typically expire after 5 minutes)

Is the "captcha_failed: Captcha verification process failed" error serious?

Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Related errors

• conflict: Database conflict, usually related to concurrent requests

  How to fix "database conflict usually related to concurrent requests" in Supabase

  MEDIUM

• bad_oauth_state: OAuth state parameter is missing or invalid

  How to fix 'bad_oauth_state: OAuth state parameter missing' in Supabase

  HIGH

• EdgeFunctionError: Boot error

  How to fix "EdgeFunctionError: Boot error" in Supabase

  HIGH

• bad_oauth_callback: OAuth callback contains an error

  How to fix 'bad_oauth_callback: OAuth callback contains an error' in Supabase

  MEDIUM

• email_not_confirmed: Email has not been confirmed

  How to fix 'email_not_confirmed: Email has not been confirmed' in Supabase

  MEDIUM

• over_email_send_rate_limit: Email send rate limit exceeded

  Email send rate limit exceeded in Supabase

  MEDIUM

Official resources & further reading

• 📚Supabase Official Documentation
• 📖
  Supabase - Enable CAPTCHA Protection(Official Docs)
• 📖
  Supabase - Error Codes(Official Docs)
• Supabase Discussion - captcha_failed error
• Supabase - OAuth login with CAPTCHA
• Supabase - Migration from hCaptcha to Turnstile
• hCaptcha Dashboard
• Cloudflare Turnstile Dashboard