Qaid
ARTICLE

Troubleshooting: Common Issues and Solutions

Solve common problems with the Qaid feedback widget including loading issues, CORS errors, and styling conflicts.

Qaid Team

When integrating the Qaid feedback widget, you may encounter various issues. This guide covers the most common problems and their solutions.

Embed Not Appearing

If the feedback widget isn’t showing up on your page, check these common causes:

Script Not Loading

Verify the script tag is correctly placed before the closing </body> tag:

<script
  src="https://unpkg.com/@qaiddev/thumbs-embed@latest/dist/qaid.umd.cjs"
  data-api-key="your-api-key"
></script>

Check the browser console for any 404 errors or network failures loading the script.

Missing or Invalid API Key

The data-api-key attribute is required. Without it, the widget won’t initialize:

<!-- This won't work - missing API key -->
<script src="https://unpkg.com/@qaiddev/thumbs-embed@latest/dist/qaid.umd.cjs"></script>

<!-- Correct - API key provided -->
<script
  src="https://unpkg.com/@qaiddev/thumbs-embed@latest/dist/qaid.umd.cjs"
  data-api-key="pk_live_abc123"
></script>

Container Element Missing

If you’re specifying a custom container, ensure it exists in the DOM:

<!-- The container must exist -->
<div id="feedback-widget"></div>

<script
  src="https://unpkg.com/@qaiddev/thumbs-embed@latest/dist/qaid.umd.cjs"
  data-api-key="your-api-key"
  data-container="#feedback-widget"
></script>

Script Loading Too Early

If you’re programmatically initializing, ensure the DOM is ready:

document.addEventListener('DOMContentLoaded', () => {
  new QaidFeedback({
    apiKey: 'your-api-key',
    // ... other options
  });
});

CORS Errors

CORS (Cross-Origin Resource Sharing) errors appear when your browser blocks requests to the Qaid API.

Symptoms

You’ll see errors like this in your console:

Access to fetch at 'https://api.qaid.dev/feedback' from origin 'https://yoursite.com'
has been blocked by CORS policy

Solutions

  1. Verify your domain is registered: In your Qaid dashboard, ensure your website’s domain is added to the allowed origins list.

  2. Check for protocol mismatches: If your site uses HTTPS, the API endpoint must also use HTTPS.

  3. Local development: When developing locally, add localhost to your allowed origins in the dashboard.

  4. Custom API endpoint: If using a custom endpoint, ensure your server sends the appropriate CORS headers:

Access-Control-Allow-Origin: https://yoursite.com
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-API-Key

Styling Conflicts

The widget uses scoped styles, but conflicts can still occur with aggressive CSS resets or global styles.

Widget Looks Broken

If buttons or modals appear unstyled or broken:

  1. Check for CSS resets that target all elements:
/* This can break the widget */
* {
  all: unset;
}

/* Or aggressive box-sizing */
* {
  box-sizing: content-box;
}

  1. Inspect conflicting styles: Use browser DevTools to identify which styles are overriding the widget.

  2. Increase specificity: The widget uses class-based selectors. If needed, you can override with more specific selectors in your custom CSS.

Button Colors Don’t Match Your Brand

Customize the widget appearance using configuration options:

<script
  src="https://unpkg.com/@qaiddev/thumbs-embed@latest/dist/qaid.umd.cjs"
  data-api-key="your-api-key"
  data-primary-color="#6366f1"
></script>

Z-Index Issues

If widget buttons are hidden behind other elements like sticky headers or modals:

Symptoms

  • Buttons appear but can’t be clicked
  • Buttons are partially or fully hidden
  • Modal opens behind other content

Solutions

  1. Check competing z-index values: The widget uses z-index: 9999 by default. Inspect your page for higher values:
// Find elements with high z-index
document.querySelectorAll('*').forEach(el => {
  const z = getComputedStyle(el).zIndex;
  if (z !== 'auto' && parseInt(z) > 9999) {
    console.log(el, z);
  }
});

  1. Adjust your page’s z-index hierarchy: Consider lowering z-index values of other elements rather than escalating further.

  2. Check stacking contexts: Even with a high z-index, elements can be trapped in a parent’s stacking context. Look for parent elements with:

    • position: relative/absolute/fixed with z-index
    • transform, filter, or opacity less than 1

When clicking the feedback buttons doesn’t open the modal:

Check for JavaScript Errors

Open your browser console (F12 → Console tab) and look for errors. Common issues:

  • “QaidFeedback is not defined”: Script didn’t load properly
  • TypeError or ReferenceError: Possible conflict with other scripts

Event Listener Conflicts

Other scripts might be preventing click events:

// Check if something is calling stopPropagation
document.addEventListener('click', (e) => {
  console.log('Click reached document:', e.target);
}, true);

Touch Events on Mobile

If the modal works on desktop but not mobile, ensure touch events aren’t being blocked by other handlers or CSS:

/* This can prevent interactions */
.some-container {
  touch-action: none;
}

Feedback Not Submitting

When feedback appears to send but doesn’t reach your dashboard:

Network Issues

  1. Check the Network tab: Look for failed requests to the feedback API
  2. Verify response status:
    • 401 - Invalid API key
    • 403 - Domain not authorized
    • 429 - Rate limited
    • 500 - Server error (temporary)

Invalid API Key

Ensure you’re using the correct API key:

// API keys start with pk_live_ or pk_test_
data-api-key="pk_live_abc123xyz"

Test keys (pk_test_) won’t send to production. Live keys (pk_live_) require a paid plan.

Offline Handling

The widget queues feedback when offline. If submissions aren’t reaching the server:

  1. Verify the user has network connectivity
  2. Check if a service worker is intercepting requests
  3. Ensure the feedback API endpoint isn’t blocked by ad blockers or privacy extensions

Video Capture Not Working

The video capture feature has specific requirements:

Browser Support

Video capture requires modern browser APIs. Check compatibility:

// Check if screen capture is supported
if (!navigator.mediaDevices?.getDisplayMedia) {
  console.log('Screen capture not supported in this browser');
}

Supported browsers:

  • Chrome 72+
  • Firefox 66+
  • Edge 79+
  • Safari 13+ (limited support)

Permission Denied

Users must grant screen recording permission:

  1. Prompt was dismissed: The user closed the permission dialog without selecting a screen
  2. Permission previously denied: Check browser settings to reset permissions
  3. Insecure context: Screen capture requires HTTPS (except localhost)

Corporate/Browser Policies

Some organizations disable screen capture via browser policies. Users will see a “Not allowed” error.

Large Video Files

If capture starts but upload fails:

  1. The recording may exceed size limits
  2. Network timeout on slow connections
  3. Check console for upload-specific errors

Console Errors and Interpretation

Here’s how to interpret common console errors:

“Failed to load resource: net::ERR_BLOCKED_BY_CLIENT”

An ad blocker or privacy extension is blocking the widget. Solutions:

  • Ask users to whitelist your domain
  • Self-host the widget script

”Uncaught TypeError: Cannot read property ‘x’ of null”

Usually means an expected DOM element doesn’t exist. Check:

  • Container element exists
  • Script loads after DOM is ready
  • No conflicting element IDs

”SecurityError: Blocked a frame with origin…”

Cross-origin iframe restrictions. The widget can’t access content inside iframes from different domains.

”QuotaExceededError”

Local storage is full. The widget uses minimal storage, but other scripts might have filled it:

// Check localStorage usage
let total = 0;
for (let key in localStorage) {
  if (localStorage.hasOwnProperty(key)) {
    total += localStorage[key].length * 2; // UTF-16 = 2 bytes per char
  }
}
console.log('localStorage used:', (total / 1024).toFixed(2), 'KB');

Debug Mode

Enable debug mode for detailed logging:

<script
  src="https://unpkg.com/@qaiddev/thumbs-embed@latest/dist/qaid.umd.cjs"
  data-api-key="your-api-key"
  data-debug="true"
></script>

This outputs:

  • State transitions
  • API requests and responses
  • Event handlers being triggered
  • Configuration being applied

Getting Help

If you’ve tried these solutions and still have issues:

Self-Service Resources

  1. Documentation: Check our installation guide and configuration reference
  2. GitHub Issues: Search existing issues or create a new one at github.com/qaiddev/thumbs-embed

Contact Support

When Reporting Issues

Include the following information for faster resolution:

  1. Browser and version (e.g., Chrome 120)
  2. Operating system (e.g., Windows 11, macOS 14)
  3. Console errors (screenshot or copy/paste)
  4. Network tab failures (screenshot showing failed requests)
  5. Your configuration (script tag or initialization code)
  6. Steps to reproduce the issue
// Gather diagnostic info
console.log({
  userAgent: navigator.userAgent,
  url: window.location.href,
  timestamp: new Date().toISOString(),
  // Add any error messages you're seeing
});

Most issues can be resolved by checking the browser console, verifying your configuration, and ensuring proper script loading. When in doubt, enable debug mode to see exactly what the widget is doing.

Back to all articles