Troubleshooting
This guide helps you diagnose and fix common issues when using InAppAI React.
Connection Issues
“Backend not responding” Error
Symptoms: Error banner shows “Backend not responding” or “Failed to connect”
Causes:
- Backend server is not running
- Wrong Agent ID
- CORS issues
- Network/firewall blocking
Solutions:
Verify your Agent ID in the dashboard
Check CORS configuration - Make sure your domain is in the allowed origins in your subscription settings
Check browser console for CORS errors:
Access to fetch at 'https://api.inappai.com' from origin 'http://localhost:5173'
has been blocked by CORS policy
- Add your domain to allowed origins in the InAppAI dashboard
TypeScript Errors
“Property ‘messages’ is missing”
Error:
Type '{}' is missing the following properties from type 'InAppAIProps':
agentId, messages, onMessagesChange
Solution: Provide all required props:
// Missing required props
<InAppAI />
// All required props provided
<InAppAI
agentId="your-agent-id"
messages={messages}
onMessagesChange={setMessages}
/>
“Type ‘Message[]’ is not assignable”
Error:
Type 'Message[]' is not assignable to type 'never[]'
Solution: Type your state correctly:
// Wrong - no type annotation
const [messages, setMessages] = useState([]);
// Correct - explicit type
import type { Message } from '@inappai/react';
const [messages, setMessages] = useState<Message[]>([]);
“Cannot find module ‘@inappai/react’”
Solution: Install the package:
npm install @inappai/react
Then import the CSS:
import '@inappai/react/styles.css';
Rendering Issues
Chat Window Not Appearing
Causes:
- Not clicking the button (popup mode)
- CSS not imported
- Z-index conflicts
Solutions:
- Import CSS:
import '@inappai/react/styles.css';
- Check display mode:
// Popup mode - click button to open
<InAppAI displayMode="popup" />
// Embedded mode - always visible
<InAppAI displayMode="embedded" />
- Fix z-index conflicts:
.inapp-ai-button,
.inapp-ai-window {
z-index: 9999 !important;
}
Messages Not Displaying
Causes:
- Empty messages array
- Messages state not updating
- onMessagesChange not called
Solutions:
- Verify messages state:
const [messages, setMessages] = useState<Message[]>([]);
console.log('Current messages:', messages); // Debug
<InAppAI
messages={messages}
onMessagesChange={(newMessages) => {
console.log('New messages:', newMessages); // Debug
setMessages(newMessages);
}}
/>
- Check message structure:
// Messages must have id, role, content
const validMessage: Message = {
id: '1',
role: 'user',
content: 'Hello',
};
Styling Not Applied
Solutions:
- Import CSS first:
import '@inappai/react/styles.css';
import { InAppAI } from '@inappai/react';
- Check custom styles format:
// Wrong - incorrect property names
customStyles={{
color: '#6366f1', // Wrong property
}}
// Correct - valid properties
customStyles={{
primaryColor: '#6366f1',
headerTitle: 'Support',
}}
Tool Execution Issues
Tools Not Being Called
Causes:
- Tool description unclear
- Tool parameters incorrect
Solutions:
- Improve tool descriptions:
// Vague description
{
name: 'addTodo',
description: 'Adds a todo', // Too vague
}
// Clear description
{
name: 'addTodo',
description: 'Add a new todo item when the user asks to create, add, or remember a task',
}
- Verify parameters schema:
{
name: 'searchProducts',
parameters: {
type: 'object', // Must be 'object'
properties: {
query: {
type: 'string', // Must match JSON Schema types
description: 'Search query',
},
},
required: ['query'], // List required params
},
}
Tool Handler Errors
Solutions:
- Wrap in try-catch:
{
name: 'deleteTodo',
handler: async ({ id }) => {
try {
await deleteTodo(id);
return { success: true };
} catch (error) {
return { success: false, error: error.message };
}
},
}
- Return proper format:
// Wrong - no return value
handler: async ({ text }) => {
addTodo(text);
}
// Correct - returns result
handler: async ({ text }) => {
const todo = addTodo(text);
return { success: true, todo };
}
Performance Issues
Slow Message Rendering
Solutions:
- Limit message history:
const MAX_MESSAGES = 100;
const displayedMessages = messages.slice(-MAX_MESSAGES);
<InAppAI
messages={displayedMessages}
onMessagesChange={setMessages}
/>
- Memoize callbacks:
const handleMessagesChange = useCallback((newMessages: Message[]) => {
setMessages(newMessages);
}, []);
<InAppAI onMessagesChange={handleMessagesChange} />
Authentication Issues
“Invalid token” Error
Causes:
- Expired JWT
- Wrong JWT configuration
- Token not sent correctly
Solutions:
Check token expiration and refresh if needed
Verify token is sent:
<InAppAI authToken={token} />
Debugging Tips
Enable Debug Logging
<InAppAI
messages={messages}
onMessagesChange={(newMessages) => {
console.log('[InAppAI] onMessagesChange:', newMessages.length);
setMessages(newMessages);
}}
onMessageSent={(msg) => {
console.log('[InAppAI] Sent:', msg);
}}
onMessageReceived={(msg) => {
console.log('[InAppAI] Received:', msg);
}}
onError={(error) => {
console.error('[InAppAI] Error:', error);
}}
/>
Check Network Requests
Open browser DevTools (F12) → Network tab:
- Look for requests to the API
- Check request/response payloads
- Verify status codes (200 = success)
Common Error Messages
“InAppAI requires controlled mode”
Fix: Provide both messages and onMessagesChange:
<InAppAI
messages={messages} // Required
onMessagesChange={setMessages} // Required
/>
“Failed to get response”
Cause: Backend returned non-200 status
Fix: Check your Agent ID and subscription status in the dashboard
“Tool ’toolName’ not found”
Cause: AI tried to call a tool that doesn’t exist
Fix: Ensure tool name matches exactly:
const tools = [
{ name: 'addTodo', ... }, // Name must match exactly
];
Getting Help
If you’re still stuck:
- Check browser console for error messages
- Create a minimal reproduction of the issue
- Search GitHub issues
- Create an issue with:
- Error message
- Code snippet
- Expected vs actual behavior
- Environment (Node version, browser, OS)
Next Steps
- Security - Security best practices
- API Reference - Complete documentation