Troubleshooting

This guide helps you resolve common issues when working with Veltix.

Common Issues

Build and Development Issues

Port already in use


# Kill processes using the ports
lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9
lsof -ti:3002 | xargs kill -9
 
# Or use different ports
pnpm dev --port 3003

Dependencies not found


# Clear cache and reinstall
pnpm store prune
rm -rf node_modules
pnpm install

Build errors


# Clean and rebuild
pnpm clean
pnpm install
pnpm build
 
# Check TypeScript errors
pnpm type-check

Memory issues during development


# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" pnpm dev
 
# Or use turbo with memory optimization
turbo dev --max-memory=4096

Component Issues

Chart not rendering


// Check data format
const data = [
  { category: 'A', value: 100 },
  { category: 'B', value: 200 }
];
 
// Ensure required props
<BarChart
  data={data}
  xField="category"
  yField="value"
  height={300}
/>

Component not updating


// Check data source configuration
const dataSource = {
  type: 'api',
  url: 'https://api.example.com/data',
  refreshInterval: 30000 // 30 seconds
};
 
// Verify data binding
<BarChart dataSource={dataSource} />

Layout issues


// Check component positioning
const component = {
  id: 'chart-1',
  position: { x: 0, y: 0 },
  size: { width: 300, height: 200 }
};
 
// Ensure grid snapping is configured
const gridConfig = {
  enabled: true,
  size: 20,
  snapThreshold: 10
};

Data Source Issues

API connection failed


# Check API server status
curl -I http://localhost:3001/health
 
# Verify environment variables
echo $REACT_APP_API_URL
 
# Check CORS configuration
# Ensure API server allows requests from frontend

Database connection issues


# Check database status
sudo systemctl status postgresql
 
# Test connection
psql -h localhost -U username -d database_name
 
# Verify connection string
echo $DATABASE_URL

WebSocket connection failed


# Check WebSocket server
curl -I ws://localhost:3001
 
# Verify WebSocket URL
echo $REACT_APP_WS_URL
 
# Check firewall settings
sudo ufw status

Performance Issues

Slow rendering


// Enable performance monitoring
import { usePerformanceMonitor } from '@veltix/ui';
 
function Dashboard() {
  const { metrics } = usePerformanceMonitor({
    fps: true,
    memory: true,
    renderTime: true
  });
 
  // Log performance issues
  useEffect(() => {
    if (metrics.fps < 30) {
      console.warn('Low FPS detected:', metrics.fps);
    }
  }, [metrics]);
 
  return <DashboardContent />;
}

High memory usage


// Implement memory optimization
import { useMemoryOptimization } from '@veltix/ui';
 
function Dashboard() {
  useMemoryOptimization({
    cleanupInterval: 60000,
    maxMemoryUsage: 100 * 1024 * 1024, // 100MB
    enableGarbageCollection: true
  });
 
  return <DashboardContent />;
}

Large bundle size


# Analyze bundle
pnpm build:analyze
 
# Check for duplicate dependencies
pnpm dedupe
 
# Use dynamic imports
const Chart = lazy(() => import('@veltix/charts'));

Theme Issues

Theme not switching


// Check theme provider setup
import { ThemeProvider } from '@veltix/ui';
 
function App() {
  return (
    <ThemeProvider
      defaultTheme="light"
      themes={['light', 'dark']}
      storageKey="veltix-theme"
    >
      <Dashboard />
    </ThemeProvider>
  );
}

Colors not updating


// Verify CSS variables
const theme = {
  colors: {
    primary: '#1890ff',
    background: '#ffffff',
    text: '#000000'
  }
};
 
// Check CSS variable usage
:root {
  --color-primary: #1890ff;
  --color-background: #ffffff;
  --color-text: #000000;
}

Network Issues

CORS errors


# Configure CORS on API server
app.use(cors({
  origin: ['http://localhost:3000', 'https://yourdomain.com'],
  credentials: true
}));

API timeout


// Increase timeout
const apiConfig = {
  timeout: 10000, // 10 seconds
  retryAttempts: 3,
  retryDelay: 1000
};

WebSocket reconnection


// Configure WebSocket reconnection
const websocketConfig = {
  reconnect: true,
  reconnectAttempts: 5,
  reconnectInterval: 1000,
  maxReconnectDelay: 30000
};

Debug Tools

Browser Developer Tools

Console debugging


// Add debug logging
const debugConfig = {
  enabled: process.env.NODE_ENV === 'development',
  level: 'info'
};
 
if (debugConfig.enabled) {
  console.log('Component rendered:', component);
  console.log('Data updated:', data);
}

Network tab

Check API requests
Verify response status
Monitor WebSocket connections
Analyze request/response headers

Performance tab

Monitor rendering performance
Check memory usage
Analyze JavaScript execution
Identify bottlenecks

React Developer Tools

Component inspection

Check component props
Monitor state changes
Verify component hierarchy
Debug component updates

Profiler

Record component renders
Analyze render times
Identify unnecessary re-renders
Optimize component performance

Veltix Debug Tools


// Enable debug mode
import { useDebugMode } from '@veltix/ui';
 
function Dashboard() {
  const { isDebugMode, debugInfo } = useDebugMode();
 
  return (
    <div>
      <DashboardContent />
      {isDebugMode && (
        <div className="debug-panel">
          <pre>{JSON.stringify(debugInfo, null, 2)}</pre>
        </div>
      )}
    </div>
  );
}

Error Handling

Error Boundaries


import { ErrorBoundary } from '@veltix/core';
 
function DashboardWithErrorBoundary() {
  return (
    <ErrorBoundary
      fallback={<div>Something went wrong</div>}
      onError={(error, errorInfo) => {
        console.error('Dashboard error:', error, errorInfo);
        // Send to error tracking service
        Sentry.captureException(error, { extra: errorInfo });
      }}
    >
      <Dashboard />
    </ErrorBoundary>
  );
}

Error Recovery


// Implement error recovery
const useErrorRecovery = () => {
  const [error, setError] = useState(null);
  const [retryCount, setRetryCount] = useState(0);
 
  const retry = useCallback(() => {
    setRetryCount(prev => prev + 1);
    setError(null);
    // Retry the operation
  }, []);
 
  const reset = useCallback(() => {
    setError(null);
    setRetryCount(0);
  }, []);
 
  return { error, retryCount, retry, reset };
};

Performance Monitoring

Metrics Collection


// Monitor key metrics
const usePerformanceMetrics = () => {
  const [metrics, setMetrics] = useState({
    fps: 0,
    memory: 0,
    renderTime: 0,
    apiResponseTime: 0
  });
 
  useEffect(() => {
    const interval = setInterval(() => {
      // Collect performance metrics
      const newMetrics = {
        fps: calculateFPS(),
        memory: performance.memory?.usedJSHeapSize || 0,
        renderTime: measureRenderTime(),
        apiResponseTime: measureAPIResponseTime()
      };
      setMetrics(newMetrics);
    }, 1000);
 
    return () => clearInterval(interval);
  }, []);
 
  return metrics;
};

Alert System


// Performance alerts
const usePerformanceAlerts = (metrics) => {
  useEffect(() => {
    if (metrics.fps < 30) {
      console.warn('Low FPS detected:', metrics.fps);
      // Send alert to monitoring service
    }
 
    if (metrics.memory > 100 * 1024 * 1024) { // 100MB
      console.warn('High memory usage:', metrics.memory);
      // Send alert to monitoring service
    }
  }, [metrics]);
};

Common Solutions

Quick Fixes

Clear cache and restart


# Clear all caches
rm -rf node_modules .next .turbo
pnpm install
pnpm dev

Reset environment


# Reset environment variables
cp .env.example .env
# Edit .env with correct values

Update dependencies


# Update all dependencies
pnpm update
pnpm install

Check configuration


# Validate configuration
pnpm type-check
pnpm lint
pnpm test

Advanced Solutions

Optimize bundle size


# Analyze bundle
pnpm build:analyze
 
# Remove unused dependencies
pnpm prune
 
# Use dynamic imports
const Chart = lazy(() => import('@veltix/charts'));

Improve performance


// Use React.memo for expensive components
const ExpensiveChart = memo(({ data }) => {
  return <Chart data={data} />;
});
 
// Use useMemo for expensive calculations
const processedData = useMemo(() => {
  return processData(data);
}, [data]);

Fix memory leaks


// Clean up event listeners
useEffect(() => {
  const handleResize = () => {
    // Handle resize
  };
 
  window.addEventListener('resize', handleResize);
  
  return () => {
    window.removeEventListener('resize', handleResize);
  };
}, []);