# How to Debug the OpenMetadata UI: A Complete Developer Guide

> Debug the OpenMetadata UI effectively using browser DevTools, React Developer Tools, and WebSocket logging. Trace UI state and API calls easily.

- Repository: [OpenMetadata/OpenMetadata](https://github.com/open-metadata/OpenMetadata)
- Tags: how-to-guide
- Published: 2026-04-23

---

**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`](https://github.com/open-metadata/OpenMetadata/blob/main/src/components/app-container/AppContainer.tsx)) — root routing and authentication wrapper
- **ExplorePage** ([`src/pages/ExplorePage/ExplorePage.component.tsx`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/axiosClient.ts):

```typescript
// 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`](https://github.com/open-metadata/OpenMetadata/blob/main/TablePage.component.tsx) | Entity detail loading |
| `GET /search/query` | [`ExplorePage.component.tsx`](https://github.com/open-metadata/OpenMetadata/blob/main/ExplorePage.component.tsx) | Search results |
| `GET /feed` | [`ActivityFeedList.component.tsx`](https://github.com/open-metadata/OpenMetadata/blob/main/ActivityFeedList.component.tsx) | Real-time notifications |
| `POST /services/ingestionPipelines` | [`AddIngestion.component.tsx`](https://github.com/open-metadata/OpenMetadata/blob/main/AddIngestion.component.tsx) | Pipeline configuration |

### Handling CORS and Proxy Issues

In development, the UI uses a proxy configuration in [`package.json`](https://github.com/open-metadata/OpenMetadata/blob/main/package.json):

```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`](https://github.com/open-metadata/OpenMetadata/blob/main/socket.service.ts).

### Verifying WebSocket State

```typescript
// 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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/store.ts).

### Configuring Redux DevTools

The store is preconfigured for DevTools extension in development:

```typescript
// 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`](https://github.com/open-metadata/OpenMetadata/blob/main/app-reducer.ts) | Configuration, theme, user preferences |
| `entity` | [`entity-reducer.ts`](https://github.com/open-metadata/OpenMetadata/blob/main/entity-reducer.ts) | Current entity data, lineage, schema |
| `explore` | [`explore-reducer.ts`](https://github.com/open-metadata/OpenMetadata/blob/main/explore-reducer.ts) | Search filters, results, aggregations |
| `lineage` | [`lineage-reducer.ts`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/package.json) engines:

```json
{
  "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`](https://github.com/open-metadata/OpenMetadata/blob/main/tsconfig.json) `paths` mapping |
| `Type error: Cannot find module '...'` | Missing dependency | Run `yarn install` or check [`package.json`](https://github.com/open-metadata/OpenMetadata/blob/main/package.json) |
| `ESLint: Parsing error` | TypeScript version mismatch | Align `@typescript-eslint` with local TS version |

### Running UI in Development Mode

```bash

# 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

```typescript
// 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

```typescript
// 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`](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata.yaml) |

## Summary

- **React Developer Tools** inspect component hierarchy, props, and hook state in [`AppContainer.tsx`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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`](https://github.com/open-metadata/OpenMetadata/blob/main/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.