How to Debug the OpenMetadata UI: A Complete Developer Guide

Use browser DevTools, React Developer Tools, and WebSocket logging to trace UI state, API calls, and real-time data flow in the OpenMetadata React frontend.

The OpenMetadata UI is a React-based single-page application that communicates with the Java backend via REST APIs and WebSockets. Debugging this frontend requires understanding the component architecture, state management patterns, and the network layer that connects to the openmetadata-service backend. This guide covers the essential tools and techniques for tracing issues in the OpenMetadata UI codebase.

Enable React Developer Tools for Component Inspection

The OpenMetadata UI is built with React 18 and uses functional components with hooks. The React Developer Tools browser extension is essential for inspecting the component tree, props, and state.

Installation and Basic Usage

1. Install the React Developer Tools extension for Chrome or Firefox
2. Open the OpenMetadata UI in your browser (typically http://localhost:3000 in development)
3. Open browser DevTools and select the Components tab

Key Inspection Points in OpenMetadata

The UI source code lives in the openmetadata-ui/src/main/resources/ui directory. Critical component hierarchies include:

• AppContainer (src/components/app-container/AppContainer.tsx) — root routing and authentication wrapper
• ExplorePage (src/pages/ExplorePage/ExplorePage.component.tsx) — main search and discovery interface
• EntityPage components (src/pages/[entity-type]/*.component.tsx) — detail views for tables, topics, dashboards, etc.

Use React DevTools to verify:

• Props drilling — check if configuration objects pass correctly through the component tree
• Hook state — inspect useState, useEffect, and custom hooks like useApplicationStore

Trace API Calls with Network Tab and Request Interceptors

The OpenMetadata UI communicates with the backend through REST APIs under /api/v1/. The Network tab in browser DevTools reveals request timing, response payloads, and error codes.

Configuring Request Logging

The UI uses Axios for HTTP requests with centralized configuration in axiosClient.ts:

// openmetadata-ui/src/main/resources/ui/src/axiosClient.ts
import axios, { AxiosResponse, AxiosError } from 'axios';

const axiosClient = axios.create({
  baseURL: process.env.REACT_APP_BASE_URL || '/api/v1',
  headers: {
    'Content-type': 'application/json',
  },
});

// Add request interceptor for debugging
axiosClient.interceptors.request.use((config) => {
  console.log('[API Request]', config.method?.toUpperCase(), config.url);
  return config;
});

// Add response interceptor for error tracing
axiosClient.interceptors.response.use(
  (response: AxiosResponse) => response,
  (error: AxiosError) => {
    console.error('[API Error]', error.response?.status, error.response?.data);
    return Promise.reject(error);
  }
);

export default axiosClient;

Key API Patterns to Monitor

Endpoint Pattern	Component/Source	Debug Purpose
GET /tables/{id}	TablePage.component.tsx	Entity detail loading
GET /search/query	ExplorePage.component.tsx	Search results
GET /feed	ActivityFeedList.component.tsx	Real-time notifications
POST /services/ingestionPipelines	AddIngestion.component.tsx	Pipeline configuration

Handling CORS and Proxy Issues

In development, the UI uses a proxy configuration in package.json:

{
  "proxy": "http://localhost:8585"
}

If API calls fail with CORS errors, verify:

1. The backend is running on the expected port
2. The proxy field matches your backend URL
3. No hardcoded localhost:8585 remains in API calls when deploying to production

Debug WebSocket Connections for Real-Time Features

OpenMetadata uses WebSockets for real-time activity feeds and notifications. The connection is managed through socket-io-client in socket.service.ts.

Verifying WebSocket State

// openmetadata-ui/src/main/resources/ui/src/utils/SocketUtils.js
import { io } from 'socket.io-client';

const socket = io(process.env.REACT_APP_SOCKET_URL || '', {
  path: '/api/v1/socket.io',
  transports: ['websocket', 'polling'],
  autoConnect: true,
});

// Debug connection events
socket.on('connect', () => {
  console.log('[Socket] Connected:', socket.id);
});

socket.on('connect_error', (err) => {
  console.error('[Socket] Connection error:', err.message);
});

socket.on('feed', (data) => {
  console.log('[Socket] Feed event:', data);
});

export default socket;

Common WebSocket Issues

Symptom	Diagnostic Step	Fix
Feed not updating	Check Network → WS tab for /api/v1/socket.io	Verify REACT_APP_SOCKET_URL environment variable
Connection drops	Monitor connect_error events in console	Check backend WebSocketResource.java health
Duplicate events	Inspect socket.id persistence	Ensure single socket instance in React context

Inspect State Management with Redux DevTools

OpenMetadata uses Redux Toolkit for global state management, with the store defined in store.ts.

Configuring Redux DevTools

The store is preconfigured for DevTools extension in development:

// openmetadata-ui/src/main/resources/ui/src/store/store.ts
import { configureStore } from '@reduxjs/toolkit';
import { appReducer } from './app-reducer';

export const store = configureStore({
  reducer: {
    app: appReducer,
    // additional reducers...
  },
  devTools: process.env.NODE_ENV !== 'production',
  middleware: (getDefaultMiddleware) =>
    getDefaultMiddleware({
      serializableCheck: {
        ignoredActions: ['app/setConfig'],
      },
    }),
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

Key State Slices to Monitor

Slice	File	Purpose
app	app-reducer.ts	Configuration, theme, user preferences
entity	entity-reducer.ts	Current entity data, lineage, schema
explore	explore-reducer.ts	Search filters, results, aggregations
lineage	lineage-reducer.ts	Graph nodes, edges, expansion state

Troubleshoot Build and Development Environment Issues

Verifying Node.js and Package Versions

OpenMetadata's UI requires specific Node.js versions. Check package.json engines:

{
  "engines": {
    "node": ">=16.0.0 <17.0.0",
    "yarn": ">=1.22.0"
  }
}

Common Build Errors

Error	Cause	Solution
Module not found: Can't resolve '@assets/...'	Path alias misconfiguration	Verify tsconfig.json paths mapping
Type error: Cannot find module '...'	Missing dependency	Run yarn install or check package.json
ESLint: Parsing error	TypeScript version mismatch	Align @typescript-eslint with local TS version

Running UI in Development Mode

# From repository root

cd openmetadata-ui/src/main/resources/ui

# Install dependencies

yarn install

# Start development server with hot reload

yarn start

# Run with specific backend URL

REACT_APP_BASE_URL=http://localhost:8585/api/v1 yarn start

Debug Authentication and Authorization Flows

The UI implements JWT-based authentication with multiple provider support (Basic, SSO, OIDC).

Tracing Login Flow

// Key files in authentication flow
// src/components/Auth/AuthProvider.tsx - Context provider
// src/components/Auth/Auth0Provider.tsx - Auth0 integration
// src/components/Auth/OidcProvider.tsx - Generic OIDC
// src/utils/AuthProvider.util.ts - Token management

Inspecting Token State

// Debug token in browser console
const token = localStorage.getItem('openmetadata-token');
console.log('Current token:', token ? `${token.substring(0, 20)}...` : 'none');

// Decode JWT payload (without verification)
const payload = JSON.parse(atob(token.split('.')[1]));
console.log('Token payload:', payload);

Common Auth Issues

Symptom	Diagnostic	Resolution
Infinite redirect loop	Check AuthProvider state vs callback URL	Verify REACT_APP_AUTH_PROVIDER env var
401 on API calls	Inspect Authorization header in Network tab	Check token expiry and refresh logic
SSO login fails	Review OidcProvider error callback	Validate OIDC configuration in openmetadata.yaml

Summary

• React Developer Tools inspect component hierarchy, props, and hook state in AppContainer.tsx and page components
• Network tab and Axios interceptors trace REST API calls to /api/v1/ endpoints with request/response logging
• WebSocket debugging verifies real-time feed connections through socket.io events and connection state
• Redux DevTools monitors global state slices for app configuration, entity data, and search results
• Build troubleshooting resolves Node.js version mismatches, path alias errors, and dependency issues
• Authentication flow debugging traces JWT tokens, OIDC callbacks, and Authorization header propagation

Frequently Asked Questions

How do I enable debug logging for API requests in the OpenMetadata UI?

Add an Axios interceptor in axiosClient.ts or open browser DevTools Network tab. For programmatic logging, insert console.log statements in the request and response interceptors, or set REACT_APP_DEBUG=true if your build supports environment-based logging flags.

Why is my WebSocket connection for real-time feeds not working?

Check the Network → WS tab in DevTools for the /api/v1/socket.io connection. Verify REACT_APP_SOCKET_URL matches your backend address, ensure the backend WebSocketResource.java is running, and confirm no proxy or firewall blocks WebSocket upgrades on port 8585.

How do I debug authentication redirects in OpenMetadata?

Use React DevTools to inspect AuthProvider context state, check localStorage for openmetadata-token, and monitor the Network tab for Authorization headers. Review browser console for OIDC callback errors, and validate that REACT_APP_AUTH_PROVIDER and REACT_APP_AUTHORITY environment variables match your IdP configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}