Troubleshooting Guide

This guide covers common issues you might encounter when embedding DataBrain and how to resolve them.

Quick Diagnostics Checklist

Before diving into specific issues, run through this checklist:

Check Browser Console

Open Developer Tools (F12) and look for errors in the Console tab

Verify Network Requests

Check the Network tab for failed API calls or 401/403 errors

Validate Token

Ensure your guest token is valid and not expired

Confirm IDs

Double-check dashboard-id and metric-id values

Test with Sample

Try the sample token/dashboard to isolate the issue

Common Issues

Dashboard Not Rendering

Component shows blank or nothing renders

Symptoms:

Empty space where dashboard should be
No errors in console
Component seems to load but shows nothing

Solutions:

Ensure plugin is imported before rendering:

// ✅ Correct - import first
import '@databrainhq/plugin/web';
import Dashboard from './Dashboard';

// ❌ Wrong - import after component
import Dashboard from './Dashboard';
import '@databrainhq/plugin/web';

Check for web component support:

// Add this check
if (!customElements.get('dbn-dashboard')) {
  console.error('DataBrain web components not loaded');
}

Verify container has height:

.dashboard-container {
  min-height: 600px; /* or 100vh */
}

Check z-index conflicts:

dbn-dashboard {
  position: relative;
  z-index: 1;
}

Dashboard loads then disappears

Symptoms:

Dashboard appears briefly then vanishes
May happen on route changes or re-renders

Solutions:

React: Prevent re-renders destroying the component:

import { useRef, useEffect } from 'react';

function Dashboard({ token }) {
  const dashboardRef = useRef(null);

  useEffect(() => {
    if (dashboardRef.current && token) {
      dashboardRef.current.setAttribute('token', token);
    }
  }, [token]);

  return (
    <dbn-dashboard
      ref={dashboardRef}
      dashboard-id="your-dashboard-id"
    />
  );
}

Vue: Use v-show instead of v-if:

<!-- ✅ Better -->
<dbn-dashboard v-show="token" :token="token" />

<!-- ❌ May cause issues -->
<dbn-dashboard v-if="token" :token="token" />

Check for parent component unmounting: Add key prop to prevent recreation

<Dashboard key="stable-key" />

Spinner loads infinitely

Symptoms:

Loading spinner never stops
Dashboard never renders

Causes & Solutions:

Invalid token:

// Check token format
console.log('Token:', token);
// Should be a UUID like: 3affda8b-7bd4-4a88-9687-105a94cfffab

Wrong dashboard ID:

// Verify dashboard-id
console.log('Dashboard ID:', dashboardId);
// Should match ID from Data App

Network blocked:

Check browser extensions (ad blockers, privacy tools)
Verify no corporate firewall blocking
Check CORS settings

Authentication & Token Errors

401 Unauthorized Error

Symptoms:

Error: “API key is invalid or expired”
401 status in network tab

Solutions:

Verify API token is correct:

# Test API token
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/guest-token/create \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"clientId":"test","dataAppName":"your-app"}'

Ensure Bearer prefix:

// ✅ Correct
headers: {
  'Authorization': `Bearer ${apiToken}`
}

// ❌ Wrong
headers: {
  'Authorization': apiToken
}

Regenerate API token:

Go to Data App settings
Generate new API token
Update environment variables

Token Expired Error

Symptoms:

“Token has expired” message
Dashboard stops working after some time

Solutions:

Set appropriate expiry time:

// Backend token generation
{
  clientId: userId,
  dataAppName: 'your-app',
  expiryTime: 3600000 // 1 hour (adjust as needed)
}

Implement token refresh:

import { useEffect, useState, useCallback } from 'react';

function useDataBrainToken() {
  const [token, setToken] = useState(null);

  const refreshToken = useCallback(async () => {
    const response = await fetch('/api/databrain/guest-token');
    const data = await response.json();
    setToken(data.token);
  }, []);

  useEffect(() => {
    refreshToken();
    
    // Refresh token every 50 minutes (if set to 1 hour expiry)
    const interval = setInterval(refreshToken, 50 * 60 * 1000);
    
    return () => clearInterval(interval);
  }, [refreshToken]);

  return token;
}

Handle token expiry event:

window.handleTokenExpiry = async (event) => {
  if (event.type === 'TOKEN_EXPIRED') {
    const newToken = await fetchFreshToken();
    // Update token in component
    document.querySelector('dbn-dashboard')
      .setAttribute('token', newToken);
  }
};

<dbn-dashboard 
  handle-server-event="handleTokenExpiry"
/>

CORS Errors

Symptoms:

“Access to fetch blocked by CORS policy”
Cross-origin errors in console

Solutions:

Generate tokens from backend (not frontend):

// ✅ Correct - backend generates token
// backend/api/token.js
const token = await generateGuestToken(userId);

// ❌ Wrong - frontend trying to generate
// Causes CORS errors
fetch('https://api.usedatabrain.com/api/v2/guest-token/create')

Whitelist your domain:

Go to Data App settings
Add your domains to allowed origins
Include all environments (dev, staging, prod)

Check for mixed content (HTTP/HTTPS):

// Ensure HTTPS if embedding on HTTPS site
const apiUrl = window.location.protocol === 'https:' 
  ? 'https://api.usedatabrain.com'
  : 'http://api.usedatabrain.com';

Display & Styling Issues

Dashboard overlaps or z-index issues

Symptoms:

Dashboard hidden behind other elements
Modals or dropdowns don’t appear correctly

Solutions:

Set appropriate z-index:

dbn-dashboard {
  position: relative;
  z-index: 10;
}

/* If dashboard needs to be on top */
dbn-dashboard::part(modal) {
  z-index: 9999;
}

Check parent container:

.dashboard-container {
  position: relative;
  z-index: auto; /* Don't create new stacking context */
}

Use isolation:

.dashboard-wrapper {
  isolation: isolate;
}

Responsive layout issues

Symptoms:

Dashboard doesn’t fit screen
Charts overlap on mobile
Scrolling issues

Solutions:

Ensure container is responsive:

.dashboard-container {
  width: 100%;
  max-width: 100vw;
  min-height: 600px;
  overflow: auto;
}

@media (max-width: 768px) {
  .dashboard-container {
    min-height: 400px;
  }
}

Set viewport meta tag:

<meta name="viewport" content="width=device-width, initial-scale=1">

Use responsive theme:

const theme = {
  general: {
    primaryColor: '#0066CC'
  },
  responsive: {
    breakpoints: {
      mobile: 768,
      tablet: 1024
    }
  }
};

Theme not applying

Symptoms:

Custom colors not showing
Font changes not working
Theme options ignored

Solutions:

Stringify theme object:

// ✅ Correct
<dbn-dashboard 
  theme={JSON.stringify(themeObject)}
/>

// ❌ Wrong
<dbn-dashboard 
  theme={themeObject}
/>

Check theme structure:

const theme = {
  general: {
    primaryColor: '#0066CC',
    backgroundColor: '#FFFFFF',
    fontFamily: 'Inter, sans-serif'
  },
  chart: {
    colors: ['#0066CC', '#00C2B8'] // Array of colors
  }
};

Verify CSS specificity:

/* Your styles might be overriding */
dbn-dashboard {
  all: initial; /* Reset if needed */
}

Performance Issues

Slow loading dashboard

Symptoms:

Dashboard takes long to load
Metrics render slowly
Poor performance with large datasets

Solutions:

Enable caching in workspace settings:

Go to Workspace Settings → Cache Settings
Enable query result caching
Set an appropriate TTL (start with 3600 seconds / 1 hour)
Choose DataBrain Caching for quick setup, or BYOC if you have your own Redis
See the Cache Settings guide for detailed setup

Apply filters to limit data:

const tokenRequest = {
  clientId: userId,
  dataAppName: 'your-app',
  params: {
    dashboardAppFilters: [{
      dashboardId: 'dashboard-id',
      values: {
        date_range: {
          startDate: '2024-01-01',
          endDate: '2024-03-31'
        }
      }
    }]
  }
};

Optimize metrics:

Reduce number of data points
Use aggregations
Limit table rows
Consider pagination

Lazy load dashboards:

import { lazy, Suspense } from 'react';

const Dashboard = lazy(() => import('./Dashboard'));

<Suspense fallback={<Loader />}>
  <Dashboard />
</Suspense>

Memory leaks

Symptoms:

Page slows down over time
Browser tab crashes
Increasing memory usage

Solutions:

Clean up on unmount:

useEffect(() => {
  const dashboard = document.querySelector('dbn-dashboard');
  
  return () => {
    // Clean up event listeners
    if (dashboard) {
      dashboard.removeEventListener('*', handleEvent);
    }
  };
}, []);

Remove event listeners:

// Don't recreate handler on every render
const handleEvent = useCallback((event) => {
  // Handle event
}, []);

Limit re-renders:

// Use memo for expensive components
const MemoizedDashboard = React.memo(Dashboard);

Cache & Redis Issues

Stale data displayed after data updates

Symptoms:

Dashboard shows old data after an ETL run or manual data update
Different users see inconsistent data

Solutions:

Reset cache after data updates:

Go to Workspace Settings → Cache Settings and click Reset Cache
This flushes all cached query results for the workspace

Reduce cache TTL:

If your data updates frequently, lower the cache expiration time
For hourly updates, set TTL to 3600 (1 hour) or less

Verify cache is the cause:

Temporarily disable caching in Workspace Settings → Cache Settings
If the data is now correct, caching was serving stale results

BYOC Redis connection failures

Symptoms:

Cache settings fail to save with “Invalid Redis credentials” error
Caching enabled but no speed improvement on repeat dashboard loads

Solutions:

Check network connectivity:

Your Redis must be reachable from DataBrain’s cloud
Verify your security group allows inbound on the Redis port (default 6379) from DataBrain’s IP (see Allow Access to our IP)
If your Redis is in a private network, contact DataBrain support for connectivity options

Verify credentials:

Double-check the host, port, and AUTH token
Ensure the AUTH token matches what’s configured on your Redis instance
Try connecting to your Redis from another client to rule out credential issues

Check Redis is running:

Ensure your Redis/Elasticache instance is in an “Available” state
Check for maintenance windows or failover events

Connection timeout:

DataBrain uses a 5-second connection timeout
If your Redis has high network latency (e.g., cross-region), connections may time out

Cache not improving performance

Symptoms:

Caching is enabled but dashboards aren’t loading faster
Every request seems to hit the database

Solutions:

Verify caching is enabled:

Go to Workspace Settings → Cache Settings and confirm the toggle is on
Confirm you’ve set a TTL greater than 0

Check cache mode:

If using Databrain Caching, it should work automatically
If using BYOC, verify your Redis connection was validated successfully (save must succeed)

Understand cache key behavior:

Cache keys include the full query, filters, workspace ID, and datasource ID
Changing any filter or parameter generates a new cache key
Dashboards with many dynamic filters may have lower cache hit rates

Check TTL is reasonable:

Very short TTLs (e.g., 10 seconds) mean cache entries expire before they can be reused
Start with 3600 (1 hour) and adjust based on your needs

Framework-Specific Issues

React
Vue
Angular

Issue: Component not updating on prop changes

// ✅ Solution: Use useEffect
useEffect(() => {
  const element = document.querySelector('dbn-dashboard');
  if (element && token) {
    element.setAttribute('token', token);
  }
}, [token]);

Issue: TypeScript errors

// Add type declaration
declare global {
  namespace JSX {
    interface IntrinsicElements {
      'dbn-dashboard': any;
      'dbn-metric': any;
    }
  }
}

Issue: Next.js SSR errors

// Use dynamic import with ssr: false
import dynamic from 'next/dynamic';

const Dashboard = dynamic(
  () => import('../components/Dashboard'),
  { ssr: false }
);

Issue: Vue warnings about unknown custom element

// vue.config.js or vite.config.js
export default {
  compilerOptions: {
    isCustomElement: tag => tag.startsWith('dbn-')
  }
}

Issue: Reactive props not updating

<!-- Use :key to force re-render -->
<dbn-dashboard 
  :key="token"
  :token="token"
  dashboard-id="id"
/>

Issue: CUSTOM_ELEMENTS_SCHEMA required

// app.module.ts
import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class AppModule { }

Issue: Change detection not working

import { ChangeDetectorRef } from '@angular/core';

constructor(private cdr: ChangeDetectorRef) {}

updateToken(newToken: string) {
  this.token = newToken;
  this.cdr.detectChanges();
}

Debugging Tips

Enable Debug Mode

Add debug logging to your implementation:

// Frontend debugging
window.DATABRAIN_DEBUG = true;

// Will log:
// - Token generation
// - API requests
// - Component lifecycle
// - Event triggers

Inspect Component State

// Check component attributes
const dashboard = document.querySelector('dbn-dashboard');
console.log({
  token: dashboard.getAttribute('token'),
  dashboardId: dashboard.getAttribute('dashboard-id'),
  options: dashboard.getAttribute('options')
});

Monitor Network Requests

// Log all DataBrain API calls
const originalFetch = window.fetch;
window.fetch = function(...args) {
  if (args[0].includes('usedatabrain.com')) {
    console.log('DataBrain API call:', args);
  }
  return originalFetch.apply(this, args);
};

Error Messages Reference

Error Message	Cause	Solution
`Token is invalid or expired`	Expired or malformed guest token	Regenerate token from backend
`Dashboard not found`	Wrong dashboard ID	Verify dashboard-id attribute
`Unauthorized access`	No permission to view dashboard	Check Data App permissions
`CORS policy error`	Frontend trying to call API directly	Generate tokens from backend
`Failed to fetch`	Network or firewall issue	Check network connectivity
`Invalid data app`	Wrong dataAppName in token request	Verify Data App name
`Rate limit exceeded`	Too many API calls	Implement rate limiting/caching

Getting Help

If you’re still stuck after trying these solutions:

Test Harness

Use our test environment to isolate issues

Sample Implementation

Check working examples in playground

API Documentation

Review complete API specs

Support

Contact our support team

Best Practices to Avoid Issues

Always generate tokens server-side

Never expose API tokens in frontend code. Use your backend to generate guest tokens.

Implement error handling

Always handle token generation failures and network errors gracefully.

Use TypeScript

Type safety helps catch issues during development.

Test across browsers

Verify your implementation works in Chrome, Firefox, Safari, and Edge.

Monitor in production

Set up error tracking (Sentry, LogRocket) to catch issues early.

Embedding Setup

Framework Integration

Component Options

Authentication & Security

Filtering & Personalization

Customization

Events & Interactions

End-User Features

AI Chat Mode

Self-Hosted Deployment

Solution Patterns

Testing & Debugging

Migration & Legacy

Additional Resources

Troubleshooting Guide

Quick Diagnostics Checklist

Common Issues

Dashboard Not Rendering

Authentication & Token Errors

Display & Styling Issues

Performance Issues

Cache & Redis Issues

Framework-Specific Issues

Debugging Tips

Enable Debug Mode

Inspect Component State

Monitor Network Requests

Error Messages Reference

Getting Help

Test Harness

Sample Implementation

API Documentation

Support

Best Practices to Avoid Issues

Embedding Setup

Framework Integration

Component Options

Authentication & Security

Filtering & Personalization

Customization

Events & Interactions

End-User Features

AI Chat Mode

Self-Hosted Deployment

Solution Patterns

Testing & Debugging

Migration & Legacy

Additional Resources

​Quick Diagnostics Checklist

​Common Issues

​Dashboard Not Rendering

​Authentication & Token Errors

​Display & Styling Issues

​Performance Issues

​Cache & Redis Issues

​Framework-Specific Issues

​Debugging Tips

​Enable Debug Mode

​Inspect Component State

​Monitor Network Requests

​Error Messages Reference

​Getting Help

Test Harness

Sample Implementation

API Documentation

Support

​Best Practices to Avoid Issues

Quick Diagnostics Checklist

Common Issues

Dashboard Not Rendering

Authentication & Token Errors

Display & Styling Issues

Performance Issues

Cache & Redis Issues

Framework-Specific Issues

Debugging Tips

Enable Debug Mode

Inspect Component State

Monitor Network Requests

Error Messages Reference

Getting Help

Best Practices to Avoid Issues