Troubleshooting

This guide covers common issues encountered when integrating the Mimeeq configurator into your website, along with solutions and diagnostic steps.

Content Security Policy (CSP)

If your website enforces a Content Security Policy, the Mimeeq embed may fail to load or behave unexpectedly unless the required domains are whitelisted. Symptoms include blank embed areas, blocked script errors in the browser console, or partial loading where the UI appears but 3D models or images don't render.

Required Domains

These domains must be allowed for the configurator to function:

Domain	CSP Directive	Purpose
*.mimeeq.com	script-src, connect-src, img-src, font-src	Embed scripts, product data, 3D models, textures, images, and fonts
jrdgrq09nk.execute-api.eu-central-1.amazonaws.com	connect-src	Mimeeq REST API — product configurations, embed initialization
anqvn4q2ee.execute-api.eu-central-1.amazonaws.com	connect-src	Pricing API — required when product pricing is enabled
graphql.mimeeqapi.com	connect-src	GraphQL API for real-time data

Additionally, these non-domain directives are needed:

Directive	Values	Reason
style-src	'unsafe-inline'	Mimeeq uses styled-components for dynamic styling. Without this, the UI renders without any styles.
img-src	blob:, data:	Used for dynamically generated images like screenshots and textures
worker-src	blob:	Web workers for 3D rendering and background processing
child-src	blob:	Same as above, needed for some browsers

Conditional Domains

These are only needed if you use specific features:

Domain	CSP Directive	When Needed
cognito-idp.eu-central-1.amazonaws.com	connect-src	Only if using Mimeeq Authentication (<mmq-auth> or programmatic sign-in)
cognito-identity.eu-central-1.amazonaws.com	connect-src	Same as above
cdn.jsdelivr.net	script-src	Only loads the glightbox lightbox library

CSP Header Example

A minimal working CSP header for Mimeeq:

Content-Security-Policy:
  script-src 'self' *.mimeeq.com;
  connect-src 'self' *.mimeeq.com jrdgrq09nk.execute-api.eu-central-1.amazonaws.com anqvn4q2ee.execute-api.eu-central-1.amazonaws.com graphql.mimeeqapi.com;
  style-src 'self' 'unsafe-inline';
  img-src 'self' *.mimeeq.com blob: data:;
  font-src 'self' *.mimeeq.com;
  worker-src blob:;
  child-src blob:;

Diagnosing CSP Issues

Open your browser's developer console and filter for "CSP" or "Content Security Policy" violations. Each blocked request will show the exact domain and directive that needs updating.

note

If you manage CSP via <meta> tags rather than HTTP headers, note that <meta> CSP tags do not support all directives (e.g., frame-ancestors is ignored). For full CSP control, use HTTP response headers.

Configurator Not Showing

If the configurator embed area is blank or nothing renders at all:

• Verify the short-code attribute matches your product's embed code exactly. This is case-sensitive.
• Check that the embed script is loaded. Look for app-embed.js in the Network tab of your browser devtools.
• Look for JavaScript errors in the console — CSP violations, network failures, or script loading errors will appear here.
• If using the template attribute, confirm the template ID exists in your admin panel. A typo or non-existent template will silently prevent loading.
• If using render-at-mount, ensure the attribute is properly set on the <mmq-embed> element.

Events Not Firing

If your custom event handlers aren't being triggered:

• Make sure event listeners are attached after the mimeeq-app-loaded event fires. Code that runs before the configurator initializes won't catch events.
• Verify event names are spelled correctly. All Mimeeq events use the mimeeq- prefix (e.g., mimeeq-add-to-cart, mimeeq-app-loaded).
• Confirm listeners are attached to document, not to the <mmq-embed> element — Mimeeq events bubble up to the document level.

// ✅ Correct — wait for app to load, listen on document
document.addEventListener('mimeeq-app-loaded', () => {
  document.addEventListener('mimeeq-add-to-cart', (event) => {
    console.log('Cart event received:', event.detail);
  });
});

Style Conflicts

If the configurator renders but looks broken or unstyled:

• Check for global CSS rules that might affect Mimeeq components. Overly broad selectors like * { box-sizing: content-box; } or div { display: flex; } can interfere.
• If style-src 'unsafe-inline' is missing from your CSP, styled-components won't inject styles and the UI will appear unstyled.
• CSS resets or normalizers applied globally can override Mimeeq's internal styles. Consider scoping them to exclude the mmq-embed element.

WebGL / 3D Rendering Issues

If the 3D viewer shows a black canvas, doesn't render, or displays an error:

• Verify that WebGL is enabled in the browser. Navigate to chrome://gpu (Chrome) or about:support (Firefox) to check GPU acceleration status.
• Some browser extensions (ad blockers, privacy tools) can interfere with WebGL contexts or block canvas rendering.
• On mobile devices, low memory conditions can cause WebGL context loss. The configurator will attempt to restore the context automatically, but persistent issues may indicate insufficient device capabilities.
• Corporate environments with GPU restrictions or virtual desktop infrastructure (VDI) may have WebGL disabled at the system level.

Multiple Embeds on One Page

Running more than one <mmq-embed> component simultaneously on the same page is not supported. The observer system is not instance-bound, so multiple embeds will interfere with each other.

Instead, use a single <mmq-embed> element and dynamically change its short-code attribute to switch between products:

const embed = document.querySelector('mmq-embed');
embed.setAttribute('short-code', 'NEW_PRODUCT_CODE');

Authentication Issues

If login forms don't appear or authentication fails silently:

• Confirm that Cognito domains (cognito-idp.eu-central-1.amazonaws.com and cognito-identity.eu-central-1.amazonaws.com) are allowed in your CSP connect-src.
• If using a custom authentication flow, ensure window.mimeeqAuth is available before calling its methods. Listen for the mimeeq-auth-loaded event.
• Check that the short-code used for the <mmq-auth> component is valid and belongs to your account.

Network and Performance

If the configurator loads slowly or assets fail intermittently:

• Add preconnect hints to establish early connections to Mimeeq origins:

  <link rel="preconnect" href="https://cdn.mimeeq.com" />
  <link rel="preconnect" href="https://jrdgrq09nk.execute-api.eu-central-1.amazonaws.com" />

• If assets load partially, check for aggressive caching or CDN proxies on your network that might strip or modify response headers.
• Corporate firewalls or proxy servers may block WebSocket connections (wss://), which are needed for real-time features. If WebSocket connections fail, the configurator will fall back to polling but real-time updates will be delayed.