Troubleshooting

Common Issues

Script not loading

Check:

Open browser console (F12)
Look for JavaScript errors
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>

Agent ID incorrect

Check:

Verify agent ID from Lua AI dashboard
Check for typos
Ensure agent is active

Solution:

// Double-check agent ID
console.log('Agent ID:', 'your-agent-id');

Script loads before DOM

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>

CSS conflicts

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

Network issues

Check:

Open Network tab in dev tools
Look for failed API requests
Check internet connection

Solution: Try staging environment:

environment: "staging"

Agent not found

Error: Agent ID doesn’t exist on serverSolution:

Verify agent exists in Lua AI dashboard
Check environment matches (staging vs production)
Try different agent ID

Authentication errors

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

Container not found

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>

Chat not visible

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

Button in wrong position

Solution:

popupButtonPositionalContainerStyles: {
  bottom: "20px !important",
  right: "20px !important",
  position: "fixed !important"
}

Colors not applying

Check:

CSS specificity conflicts
Theme overrides

Solution:

// Use more specific styles
popupButtonStyles: {
  backgroundColor: "#ff6b6b !important"
}

Custom CSS not working

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

Microphone not working

Check:

HTTPS enabled (required for microphone)
Browser permissions granted
Microphone physically working

Solution:

Use HTTPS (voice requires secure connection)
Check browser permissions
Test microphone in other apps

Permission denied

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

Test in Staging First

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

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

Use Feature Detection

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

Handle Errors Gracefully

window.addEventListener('message', function(event) {
  if (event.data?.type === 'LUA_POP_ERROR') {
    console.error('LuaPop Error:', event.data.error);
    // Show fallback UI
    showFallbackSupport();
  }
});

Getting Started

Configuration

Integration

Features

Help

Troubleshooting

Common Issues

Widget Not Appearing

Button Shows But Chat Won’t Open

Embedded Mode Issues

Styling Issues

Voice Chat Issues

Debug Mode

Browser Console Checks

Verify LuaPop Loaded

Check for Errors

Getting Help

Diagnostic Information

Support Channels

Discord Community

Documentation

Email Support

Prevention Tips

Next Steps

Configuration

Events

​Common Issues

​Widget Not Appearing

​Button Shows But Chat Won’t Open

​Embedded Mode Issues

​Styling Issues

​Voice Chat Issues

​Debug Mode

​Browser Console Checks

​Verify LuaPop Loaded

​Check for Errors

​Getting Help

​Diagnostic Information

​Support Channels

Discord Community

Documentation

Email Support

​Prevention Tips

​Next Steps

Configuration

Events

Common Issues

Widget Not Appearing

Button Shows But Chat Won’t Open

Embedded Mode Issues

Styling Issues

Voice Chat Issues

Debug Mode

Browser Console Checks

Verify LuaPop Loaded

Check for Errors

Getting Help

Diagnostic Information

Support Channels

Prevention Tips

Next Steps