Troubleshooting the Kapa React SDK

This guide addresses common issues you might encounter when using the Kapa React SDK and provides solutions to help you resolve them.

Error: "Network error while fetching answer"

This error occurs when the SDK cannot establish a connection to the Kapa backend.

Possible causes:

1. Network connectivity issues
2. Firewall or CORS restrictions
3. Invalid integration ID

Solutions:

1. Check your network connection and ensure you can access https://proxy.kapa.ai
2. Verify that your integration ID is correct
3. Ensure that your domain is allowed in your Kapa integration settings
4. Check browser console for specific network errors

// Example with error handling
function ChatComponent() {
  const { error, submitQuery } = useChat();

  return (
    <div>
      {error && (
        <div className="error-message">
          <p>Error: {error}</p>
          <button onClick={() => submitQuery(lastQuery)}>
            Try again
          </button>
        </div>
      )}
      {/* Rest of component */}
    </div>
  );
}

Error: "Unexpected status code"

This indicates the server responded, but with an error status code.

Possible causes:

1. Rate limiting
2. Invalid or expired integration ID
3. Server-side issues

Solutions:

1. Check if you're exceeding usage limits
2. Verify your integration ID is valid
3. Contact Kapa support if the issue persists

Error: "Error in verifying browser for feedback submission"

This happens when the captcha verification fails.

Possible causes:

1. Missing captcha configuration
2. Network issues preventing captcha verification
3. User has blocked third-party scripts
4. You're seeing this error with hCaptcha during local development

Solutions:

1. Ensure hasConsentForCaptcha is set to true in the provider

2. Check that the user's browser allows third-party scripts

3. Try an alternative captcha provider:

   <KapaProvider
     integrationId="your-integration-id"
     botProtectionMechanism="hcaptcha" // Try alternative provider
     callbacks={{}}
   >
     <YourApplication />
   </KapaProvider>

4. hCaptcha does not support localhost or 127.0.0.1 commonly used during local development. Use a fake local domain instead, see hCaptcha documentation.

Error: "useChat must be used within a KapaSDKProvider"

This error occurs when you use the useChat hook outside of the KapaProvider component.

Solution:

Make sure all components using the useChat hook are descendants of a KapaProvider component:

// Correct structure
function App() {
  return (
    <KapaProvider integrationId="your-id" callbacks={{}}>
      <ChatComponent /> {/* This can use useChat */}
    </KapaProvider>
  );
}

Error: "Named export 'CacheLocation' not found"

Named export 'CacheLocation' not found. The requested module
'@fingerprintjs/fingerprintjs-pro-react' is a CommonJS module, which may not
support all module.exports as named exports.

This error occurs when the React SDK attempts to render on the server in SSR frameworks like Astro, Next.js, or Gatsby.

Cause: The Kapa React SDK is client-side only and contains browser-specific dependencies (like reCAPTCHA) that cannot run in a server environment. When your framework attempts to render the SDK components on the server, it encounters modules that are only available in browser environments.

Solution: You need to ensure your Kapa components only render on the client side. Refer to the SSR implementation guide for framework-specific instructions on how to properly configure client-only rendering.

FAQ

reCAPTCHA badge visible when previewing SDK locally

Google reCAPTCHA may show its badge during local development for testing, even if it's set to be invisible in production. On registered domains, the badge stays hidden as expected.

Debugging tips

1. Enable console logging in callbacks:

   callbacks={{
     askAI: {
       onQuerySubmit: (data) => console.log('Query submitted:', data),
       onAnswerGenerationCompleted: (data) => console.log('Answer completed:', data)
     }
   }}

2. Inspect network requests in browser developer tools to see API calls and responses

3. Check React component hierarchy to ensure components using useChat are properly nested under the provider

4. Verify integration settings in your Kapa dashboard, especially allowed domains

Getting additional help

If you're still experiencing issues, contact the Kapa support team.

Provide the following information when reporting issues:

• SDK version
• Environment, browser, and OS details
• Error messages from console
• Steps to reproduce the issue