Skip to main content

​
Common Issues

​
Widget Not Appearing

Check:
  1. Open browser console (F12)
  2. Look for JavaScript errors
  3. Verify script URL is correct
Solution:
<!-- Ensure correct script URL -->
<script src="https://lua-ai-global.github.io/lua-pop/lua-pop.umd.js"></script>
Check:
  1. Verify agent ID from Lua AI dashboard
  2. Check for typos
  3. Ensure agent is active
Solution:
// Double-check agent ID
console.log('Agent ID:', 'your-agent-id');
Check:
  • Is script in <head> instead of before </body>?
Solution:
<!-- Move script to end of body -->
<body>
  <!-- Your content -->
  
  <!-- LuaPop script should be here -->
  <script src="..."></script>
</body>
Check:
  • Other chat widgets interfering
  • CSS hiding the button
Solution:
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:
environment: "staging"
Error: Agent ID doesn’t exist on serverSolution:
  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:
// Remove auth token to test
window.LuaPop.init({
  agentId: "your-agent-id",
  // authToken: "...",  // Comment out temporarily
});

​
Embedded Mode Issues

Error: Target container doesn’t existSolution:
<!-- Ensure container exists -->
<div id="chat-container"></div>

<script>
  // Wait for DOM to load
  window.addEventListener('load', () => {
    window.LuaPop.init({
      displayMode: "embedded",
      embeddedDisplayConfig: {
        targetContainerId: "chat-container" // Must match
      }
    });
  });
</script>
Check:
  • Container has dimensions (width/height)
  • Container is not hidden by CSS
Solution:
#chat-container {
  width: 400px;
  height: 600px;
  display: block;
  visibility: visible;
}

​
Styling Issues

Solution:
popupButtonPositionalContainerStyles: {
  bottom: "20px !important",
  right: "20px !important",
  position: "fixed !important"
}
Check:
  • CSS specificity conflicts
  • Theme overrides
Solution:
// Use more specific styles
popupButtonStyles: {
  backgroundColor: "#ff6b6b !important"
}
Solution: Add !important or increase specificity:
.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 permissionSolution: Widget shows fallback to text input automatically

​
Debug Mode

Enable detailed logging: 
// 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

// In browser console
console.log(window.LuaPop);
// Should show the LuaPop object

console.log(window.LuaPop.config);
// Should show your configuration

​
Check for Errors

// 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: 
// 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

Discord Community

Get real-time help from the community

Documentation

Search these docs

Email Support

Get help from our team

​
Prevention Tips

// Always test new changes in staging
const env = process.env.NODE_ENV === 'production' 
  ? 'production' 
  : 'staging';

window.LuaPop.init({
  agentId: "your-agent-id",
  environment: env
});

// Check if LuaPop loaded
if (window.LuaPop) {
  window.LuaPop.init({ /* config */ });
} else {
  console.error('LuaPop failed to load');
  // Show fallback support option
}

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

Configuration

Review configuration options

Events

Learn about event system