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

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>

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>
  );
}

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