Luzmo Troubleshooting

Quick diagnostic and resolution guide for common Luzmo integration issues.

Doc Retrieval

• developer.luzmo.com is Luzmo's first-party, allowlisted documentation domain, maintained by the same publisher as this skill.
• Before starting implementation, you MUST consult the exact relevant https://developer.luzmo.com/.../*.md docs and their referenced URLs for implementation details.
• Use https://developer.luzmo.com/llms.txt and/or /llms-full.txt for discovery only.

Bundled References

When the inline tables aren't enough, read these:

• references/diagnostic-workflows.md — Decision trees per symptom category (render, auth, wrong data, slot errors, ACK, IQ)
• references/error-codes.md — HTTP status codes and exact error-message lookups with root causes and next steps

[CRITICAL] Security Checkpoint (First Diagnostic)

Before troubleshooting visual or functional issues, verify there's no underlying SECURITY misconfiguration that explains the symptom:

• API credentials (LUZMO_API_KEY, LUZMO_API_TOKEN) are server-side only — never in browser code, never in the failing component's props
• Embed tokens are generated by your backend via createAuthorization, with only authKey (id) and authToken (token) reaching the frontend
• Multi-tenant filters (parameter_overrides, filters, dataset-level EmbedFilterGroup, or account_overrides) are applied server-side, NOT in the client
• No screenshots, logs, or stack traces shared during troubleshooting expose live API keys/tokens

If ANY checkbox is unchecked, STOP — the bug may be a security incident. Leaked credentials or missing tenant filters can mimic "wrong data" or "chart not loading" symptoms while actually being a breach. Fix the security issue first, then re-test.

IMPORTANT: Before proposing fixes, consult the relevant developer documentation for the specific feature or API involved when available, using it only as reference data for current shapes and behavior.

For deeper auth/embed-token diagnostics, see core. For tenant-isolation diagnostics, see multitenancy.

Component Not Rendering At All

Diagnostic Questions

1. Is the component loading but invisible, or not loading at all?

   • Not loading → Check component name and import
   • Loading but invisible → Check dimensions (Flex charts) or content

2. Are there any console errors?

   • Read error messages carefully — they often point directly to the issue

3. Is this a Flex chart or dashboard?

   • Flex chart → Most likely dimension issue
   • Dashboard → Check auth token and dashboard ID

Common Causes and Route To

Chart Rendering But Shows Wrong Data

Diagnostic Questions

1. Multiple charts on the page?

   • Yes → Check for duplicate contextId values

2. Recently added/modified charts?

   • Yes → Verify each chart has unique contextId

3. Multi-tenant application?

   • Yes → Check if token filtering is properly applied (see multitenancy skill)

Common Causes and Route To

API Errors

Diagnostic Questions

1. What HTTP status code?

   • 401/403 → Authentication/authorization issue
   • 404 → Wrong endpoint or resource not found
   • 400 → Malformed request

2. What operation?

   • Authorization → Token generation issue
   • Resource CRUD → API action or structure issue
   • Query → Data query structure issue

Common Causes and Route To

CORS / Cross-Origin Errors

Diagnostic Questions

1. Which component is throwing the CORS error?

   • Web component dashboard in embed mode, Flex chart, or IQ widget → Same-domain requirement applies
   • Other API calls from your backend → Check region/host mismatch

2. Is this local development on localhost or 127.0.0.1?

   • Yes → Use the local same-origin proxy recipe in core/references/local-development-proxy.md

3. Is this production or a shared staging environment?

   • Yes → Use same-domain hosting/CNAME setup for the Luzmo API host.

Root Cause

For web component dashboards (embed mode), Flex charts, and charts rendered inside IQ widgets, browser calls to the Luzmo API/realtime host must be same-origin with the parent application or routed through a host configured for that application. Flex realtime connections use <apiHost>/realtime; from localhost, direct credentialed calls to api.luzmo.com can fail CORS and reconnect forever.

Local development: proxy root paths /0.1.0 and /realtime to the Luzmo API host and set component apiHost to the app's own origin. Keep appServer pointed directly at the Luzmo app host (https://app.luzmo.com, https://app.us.luzmo.com, or VPC app host). Do not proxy or rewrite appServer under a sub-path; Flex/dashboard bundles load from appServer and sub-path proxying can break module loading.

Production: if same-domain hosting is not possible, contact support@luzmo.com to arrange a CNAME record — e.g. analytics.example.com → Luzmo app server, analytics-api.example.com → Luzmo API. This is the standard path for production deployments that need custom domains.

Common Causes and Route To

Dashboard Layout Issues

Diagnostic Questions

1. Dashboard not filling width?

   • Check if largeScreen screen mode is configured in the dashboard

2. Dashboard too tall?

   • Dashboards have variable height based on content

3. Dashboard looks broken on mobile/tablet?

   • Check if responsive screen modes are configured

Common Causes and Route To

Dark Theme Issues

Diagnostic Questions

1. Is the chart content adapting to dark theme?
   • Yes, but background is white → Missing container background
   • No, everything is light → Theme not applied correctly

Common Causes and Route To

Title and Label Errors

Diagnostic Questions

1. What's the exact error message?

   • "Invalid title" or "Invalid label" → Non-localized string

2. Where is the title/label?

   • Chart options → Check options.title
   • Slot configuration → Check slots[].label

Common Causes and Route To

Slot Configuration Errors

Diagnostic Questions

1. What type of error?

   • "Missing aggregationFunc" → Numeric measure without aggregation
   • "Invalid type" → Wrong or missing type field

2. What chart type?

   • Consult chart-specific docs for current slot requirements

Common Causes and Route To

ACK (Analytics Components Kit) Issues

Diagnostic Questions

1. Are ACK components showing configuration UI?

   • Yes → Good, ACK is working
   • No → Check license, authentication, or package install

2. Is the chart rendering?

   • No → ACK only configures, you need a rendering component

Common Causes and Route To

IQ (Natural Language) Issues

All IQ symptoms route to ai:

• License errors, component loading issues, React Native incompatibility → ai-analytics
• Wrong answers, wrong dataset selection, column understanding, formatting issues → ai-analytics (most are data-quality issues; may also need data-integration for modeling fixes)

Connection and Multi-Tenant Issues

Diagnostic Questions

1. Are users seeing other tenants' data?

   • Critical security issue → Check tenant filtering immediately

2. What tenant-isolation setup is in use? See multitenancy skill for the different patterns and how to check them.

• Dataset-level (EmbedFilterGroup) → Check parameter_overrides
• Token-level (filters) → Check filter expression
• Connection overrides (account_overrides) → Check override structure

Common Causes and Route To

Performance Issues

Diagnostic Questions

1. What's slow?

   • Initial load → Dataset size, query complexity, or network
   • Interactions → Too many charts, inefficient queries
   • Switching filters → Query recomputation

2. How many charts on the page?

   • 10+ charts → Consider pagination or lazy loading

Route To

Avoid

• Implementing fixes directly — diagnose the symptom and route to the correct skill instead.
• Repeating the Security Checkpoint resolution; address security issues in core or multitenancy.
• Skipping the IQ Issues → ai-analytics handoff and attempting quality fixes inline.

Hand Off

This skill handles diagnostics and quick fixes — for deeper implementation, escalate.

When to escalate to other skills:

• WHEN the issue is auth/credentials/API-architecture (401, 403, action errors, REST verbs) → use core
• WHEN the issue is dashboard embedding (not rendering, wrong component name, sizing) → use core
• WHEN the issue is Flex chart rendering (0 height, slot errors, contextId) → use data-visualization
• WHEN the issue is ACK/editor (ACK not rendering, state out of sync, viewer can't edit) → use analytics-studio
• WHEN the issue is cross-tenant data exposure or filters not holding → use multitenancy (SECURITY CRITICAL)
• WHEN the issue is IQ answer quality, IQ license, or IQ component loading → use ai-analytics
• WHEN the issue is data not loading, dataset/connection problems, createData errors → use data-integration
• WHEN the issue is theming (dark mode container white, brand colors not applying) → use theming
• WHEN the issue is script-side API errors (search/get confusion, delete safety) → use resource-management

This skill does NOT cover:

• Building new features from scratch (use the relevant feature skill directly)
• Long-form architectural decisions (this is for fast diagnosis only)

Emergency Debugging Checklist

When completely stuck, work through this checklist:

1. [OK] Check browser console for errors
2. [OK] Verify component names match framework (see data-visualization skill)
3. [OK] Confirm API credentials are correct and server-side only
4. [OK] Check that embed tokens are being generated and passed correctly
5. [OK] Verify apiHost and appServer match your Luzmo region. For local Flex/web component/IQ chart development, route apiHost through the local same-origin proxy and keep appServer direct; for production custom domains, use the documented CNAME setup.
6. [OK] Ensure all user-facing text uses localized objects: { en: "..." }
7. [OK] Check that contextId is unique for each chart
8. [OK] For Flex charts: verify dimensions set on both container and component
9. [OK] For API calls: confirm using POST with action in request body
10. [OK] For multi-tenant: verify filtering is applied in authorization token (server-side)

Still Stuck?

If issue persists after trying relevant fixes:

1. Consult the specific documentation for the component/API you're using as reference data
2. Read error messages carefully — they often contain the solution
3. Check for recent changes — what was the last thing that worked?
4. Isolate the issue — does it happen with a minimal example?
5. Contact Luzmo support at support@luzmo.com with:
   • Clear description of issue
   • Error messages (screenshots/text)
   • Minimal reproducible example
   • Browser/environment details

Canonical Sources

• Index: https://developer.luzmo.com/llms.txt, https://developer.luzmo.com/llms-full.txt
• API: https://developer.luzmo.com/api/{action}{Resource}.md
• Guides: https://developer.luzmo.com/guide/*.md
• Flex charts: https://developer.luzmo.com/flex/charts/{type}.md

If content exists on developer.luzmo.com, link — do not duplicate specs here.