> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Common issues and solutions for LuaPop
## Common Issues
### Widget Not Appearing
**Check:**
1. Open browser console (F12)
2. Look for JavaScript errors
3. Verify script URL is correct
**Solution:**
```html theme={null}
```
**Check:**
1. Verify agent ID from Lua AI dashboard
2. Check for typos
3. Ensure agent is active
**Solution:**
```javascript theme={null}
// Double-check agent ID
console.log('Agent ID:', 'your-agent-id');
```
**Check:**
* Is script in `` instead of before ``?
**Solution:**
```html theme={null}
```
**Check:**
* Other chat widgets interfering
* CSS hiding the button
**Solution:**
```javascript theme={null}
popupButtonStyles: {
zIndex: "99999", // Higher z-index
display: "block !important"
}
```
### Button Shows But Chat Won't Open
**Check:**
1. Open Network tab in dev tools
2. Look for failed API requests
3. Check internet connection
**Solution:** Try staging environment:
```javascript theme={null}
environment: "staging"
```
**Error:** Agent ID doesn't exist on server
**Solution:**
1. Verify agent exists in Lua AI dashboard
2. Check environment matches (staging vs production)
3. Try different agent ID
**Check:**
* Invalid auth token
* Expired session
**Solution:**
```javascript theme={null}
// Remove auth token to test
window.LuaPop.init({
agentId: "your-agent-id",
// authToken: "...", // Comment out temporarily
});
```
### Embedded Mode Issues
**Error:** Target container doesn't exist
**Solution:**
```html theme={null}
```
**Check:**
* Container has dimensions (width/height)
* Container is not hidden by CSS
**Solution:**
```css theme={null}
#chat-container {
width: 400px;
height: 600px;
display: block;
visibility: visible;
}
```
### Styling Issues
**Solution:**
```javascript theme={null}
popupButtonPositionalContainerStyles: {
bottom: "20px !important",
right: "20px !important",
position: "fixed !important"
}
```
**Check:**
* CSS specificity conflicts
* Theme overrides
**Solution:**
```javascript theme={null}
// Use more specific styles
popupButtonStyles: {
backgroundColor: "#ff6b6b !important"
}
```
**Solution:** Add `!important` or increase specificity:
```css theme={null}
.lua-pop-button {
background: #ff6b6b !important;
}
/* Or use higher specificity */
body .lua-pop-widget .lua-pop-button {
background: #ff6b6b;
}
```
### Voice Chat Issues
**Check:**
1. HTTPS enabled (required for microphone)
2. Browser permissions granted
3. Microphone physically working
**Solution:**
* Use HTTPS (voice requires secure connection)
* Check browser permissions
* Test microphone in other apps
**Issue:** User denied microphone permission
**Solution:** Widget shows fallback to text input automatically
## Debug Mode
Enable detailed logging:
```javascript theme={null}
// Use staging for verbose logging
window.LuaPop.init({
agentId: "your-agent-id",
environment: "staging" // More detailed logs
});
// Check console for detailed information
console.log('LuaPop config:', window.LuaPop.config);
```
## Browser Console Checks
### Verify LuaPop Loaded
```javascript theme={null}
// In browser console
console.log(window.LuaPop);
// Should show the LuaPop object
console.log(window.LuaPop.config);
// Should show your configuration
```
### Check for Errors
```javascript theme={null}
// Look for errors in console
// Common errors:
// - Script loading failed
// - Agent not found
// - Network errors
// - Permission denied
```
## Getting Help
### Diagnostic Information
When reporting issues, include:
```javascript theme={null}
// Browser info
console.log('Browser:', navigator.userAgent);
// LuaPop version
console.log('LuaPop:', window.LuaPop);
// Configuration
console.log('Config:', window.LuaPop.config);
// Current errors
console.error('Errors:', /* copy error messages */);
```
### Support Channels
Get real-time help from the community
Search these docs
Get help from our team
## Prevention Tips
```javascript theme={null}
// Always test new changes in staging
const env = process.env.NODE_ENV === 'production'
? 'production'
: 'staging';
window.LuaPop.init({
agentId: "your-agent-id",
environment: env
});
```
```javascript theme={null}
// Check if LuaPop loaded
if (window.LuaPop) {
window.LuaPop.init({ /* config */ });
} else {
console.error('LuaPop failed to load');
// Show fallback support option
}
```
```javascript theme={null}
window.addEventListener('message', function(event) {
if (event.data?.type === 'LUA_POP_ERROR') {
console.error('LuaPop Error:', event.data.error);
// Show fallback UI
showFallbackSupport();
}
});
```
## Next Steps
Review configuration options
Learn about event system