# How to Debug Apache Superset Frontend: Complete tRPC and Next.js API Debugging Guide

> Debug Apache Superset frontend effectively. Master tRPC and Next.js API debugging with Node inspector, detailed logs, and strategic breakpoints for faster resolution.

- Repository: [Superset/superset](https://github.com/superset-sh/superset)
- Tags: how-to-guide
- Published: 2026-03-08

---

**Debug Apache Superset frontend issues by tracing requests from the Next.js proxy through the tRPC backend, using Node inspector, verbose logging, and targeted breakpoints in workspace routers and database procedures.**

When debugging the Apache Superset frontend in the `superset-sh/superset` repository, most critical errors originate in the **tRPC-powered API** layer that serves the React UI. This Next.js-based application uses a sophisticated proxy and router architecture connecting `apps/web` to `apps/api`, requiring specific techniques to trace failures from browser requests through to database queries. Understanding how to navigate the proxy configuration, tRPC entry points, and business logic procedures is essential for resolving frontend data loading and authentication errors.

## Understanding the Frontend-to-Backend Architecture

Superset’s frontend debugging requires tracing requests through three distinct layers. The **Next.js proxy** ([`apps/web/src/proxy.ts`](https://github.com/superset-sh/superset/blob/main/apps/web/src/proxy.ts)) forwards authenticated requests from the browser to the API workspace, which handles them via the tRPC route handler at `apps/api/src/app/api/trpc/[trpc]/route.ts`. All public procedures are composed in the **root router** ([`packages/trpc/src/root.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/root.ts)) and organized by domain under `packages/trpc/src/router/<name>`. When the UI fails to load data, the issue typically resides in the API’s error handling, procedure logic, or database connection rather than the React components themselves.

## Three-Layer Debugging Strategy

### 1. Entry Point and Routing Verification

Start by confirming requests reach the tRPC handler in `apps/api/src/app/api/trpc/[trpc]/route.ts`. This file sets up the fetch handler and logs errors to `console.error` with the failing path. If the dev server isn’t running the `apps/api` workspace, or if the proxy matcher in [`apps/web/src/proxy.ts`](https://github.com/superset-sh/superset/blob/main/apps/web/src/proxy.ts) is misconfigured, the frontend will receive `404 Not Found` responses before any procedure logic executes.

### 2. Router and Procedure Isolation

Identify which tRPC router (e.g., `workspace`, `project`, `agent`) handles the failing frontend call by checking [`packages/trpc/src/root.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/root.ts). Each sub-router lives under `packages/trpc/src/router/<name>`. Insert `console.log` or `debugger` statements inside the specific procedure to inspect incoming input and execution context. A "Method not found" error typically indicates a typo in the procedure name or a missing export in the `appRouter` object.

### 3. Business Logic and Side Effects

The procedure calls services in `apps/desktop`, `packages/*`, or the Drizzle ORM schema. Common failure points include the **desktop notifications server** ([`apps/desktop/src/main/lib/notifications/server.ts`](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/main/lib/notifications/server.ts)) and the data-access layer under `packages/db`. Enable `DEBUG=drizzle:*` to inspect generated SQL, or check for unhandled promises causing hangs in long-running requests.

## Essential Debugging Commands and Workflow

| Step | Command / Action | What It Gives You |
|------|------------------|-------------------|
| **Start only the API** | `bun dev --filter apps/api` | Spins up the API server on `http://localhost:3000` (or the port defined in `.env.example`). |
| **Enable verbose Node debugging** | `bun dev --inspect --filter apps/api` | Opens the V8 inspector at `ws://127.0.0.1:9229`. Attach Chrome DevTools or VS Code to set breakpoints in TypeScript sources. |
| **Increase library logging** | `DEBUG=* bun dev --filter apps/api` | tRPC and internal modules emit `debug` messages to `stdout`, showing request flow and middleware execution. |
| **Inspect tRPC errors** | Check the error handler in `apps/api/src/app/api/trpc/[trpc]/route.ts` | Prints `console.error` with the failing path and stack traces. |
| **Force a request** | `curl -X POST http://localhost:3000/api/trpc/<router>.<procedure> -H "Content-Type: application/json" -d '{"json":{...}}'` | Reproduces the exact call failing in the UI to isolate network vs. logic issues. |
| **Run backend unit tests** | `bun test packages/trpc` | Confirms procedures behave correctly in isolation without frontend variables. |
| **Check database queries** | `DEBUG=drizzle:*` or add `console.log` in `packages/db/src` | Shows generated SQL and parameters for debugging data retrieval issues. |

## Common Frontend-Backend Integration Gotchas

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| **`404 Not Found` on `/api/trpc/...`** | The dev server isn’t running the `apps/api` workspace, or the proxy `matcher` in [`apps/web/src/proxy.ts`](https://github.com/superset-sh/superset/blob/main/apps/web/src/proxy.ts) fails to forward requests. | Run `bun dev --filter apps/api` and verify the proxy configuration forwards `/api` and `/trpc` paths. |
| **tRPC "Method not found"** | Procedure name typo or router not exported in [`packages/trpc/src/root.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/root.ts). | Verify the router definition and ensure it is included in the `appRouter` object. |
| **`env_mismatch` warning** | The desktop notifications hook ([`apps/desktop/src/main/lib/notifications/server.ts`](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/main/lib/notifications/server.ts)) contacts the wrong backend (dev vs. prod). | Align `process.env.NODE_ENV` or set `SUPERSET_DEBUG_HOOKS=1` to force dev mode. |
| **Database connection errors** | Missing environment variables (`DATABASE_URL`, `NEON_PROJECT_ID`). | Copy `.env.example` to `.env.local` and fill required values; the server reads them via `shared/env.shared`. |
| **Long-running request hangs** | Unhandled promise in a procedure (missing `await`). | Add proper `await`/`try…catch` blocks and log errors at the procedure level. |

## Practical Debugging Examples

### Starting the API with Node Inspector

Enable V8 inspector support to set breakpoints directly in TypeScript source files:

```bash

# In the repository root

DEBUG=* bun dev --inspect --filter apps/api

```

Open Chrome at `chrome://inspect` and select "Open dedicated DevTools for Node" to debug files like [`packages/trpc/src/router/workspace/workspace.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/router/workspace/workspace.ts) at runtime.

### Adding Debug Statements to tRPC Procedures

Insert logging inside any router procedure to inspect inputs and database responses:

```typescript
// packages/trpc/src/router/workspace/workspace.ts
export const workspaceRouter = router({
  getDetails: protectedProcedure
    .input(z.object({ workspaceId: z.string() }))
    .query(async ({ ctx, input }) => {
      console.log('🛠 getDetails called with', input);
      const result = await ctx.db.workspace.findUnique({
        where: { id: input.workspaceId },
      });
      return result;
    }),
});

```

Logs appear in the terminal where `bun dev` is running, showing the exact data passed from the frontend.

### Triggering Procedures with curl

Bypass the frontend entirely to test API logic in isolation:

```bash
curl -X POST http://localhost:3000/api/trpc/workspace.getDetails \
  -H "Content-Type: application/json" \
  -d '{"json":{"workspaceId":"wrk_123"}}'

```

If the procedure throws, the error handler in `apps/api/src/app/api/trpc/[trpc]/route.ts` formats and prints the stack trace.

### VS Code Debugger Configuration

Add this launch configuration to [`.vscode/launch.json`](https://github.com/superset-sh/superset/blob/main/.vscode/launch.json) for integrated debugging:

```json
{
  "type": "node",
  "request": "launch",
  "name": "Debug Superset API",
  "runtimeExecutable": "bun",
  "runtimeArgs": ["dev", "--filter", "apps/api"],
  "port": 9229,
  "skipFiles": ["<node_internals>/**"]
}

```

Place breakpoints in any backend file and run the "Debug Superset API" configuration to step through execution while testing frontend features in the browser.

## Key Files for Frontend Debugging

| Component | File Path | Description |
|-----------|-----------|-------------|
| **API Entry Point** | `apps/api/src/app/api/trpc/[trpc]/route.ts` | Sets up the tRPC fetch handler, logs errors, and exports `GET`/`POST` methods for the frontend to consume. |
| **Root tRPC Router** | [`packages/trpc/src/root.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/root.ts) | Combines all sub-routers (`workspace`, `project`, `agent`) into a single `appRouter` that defines the API surface. |
| **tRPC Initialization** | [`packages/trpc/src/trpc.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/trpc.ts) | Configures the `initTRPC` instance, context creator, and middleware stack used by all procedures. |
| **Workspace Router** | [`packages/trpc/src/router/workspace/workspace.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/router/workspace/workspace.ts) | Example CRUD router showing how procedures access the database and handle frontend requests. |
| **Frontend Proxy** | [`apps/web/src/proxy.ts`](https://github.com/superset-sh/superset/blob/main/apps/web/src/proxy.ts) | Next.js proxy forcing authentication redirects and forwarding `/api` and `/trpc` calls to the API workspace. |
| **Desktop Notifications** | [`apps/desktop/src/main/lib/notifications/server.ts`](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/main/lib/notifications/server.ts) | Handles hook callbacks (`/hook/complete`) and prints diagnostic warnings for agent-side events affecting the UI. |
| **Database Schema** | `packages/db/src/schema/*` | Drizzle ORM schema definitions; inspect these to understand data structures queried by frontend features. |
| **Environment Variables** | `.env.example` | Lists required variables (`NEXT_PUBLIC_API_URL`, `DATABASE_URL`) for local development connectivity. |

## Summary

- **Trace the request flow** from [`apps/web/src/proxy.ts`](https://github.com/superset-sh/superset/blob/main/apps/web/src/proxy.ts) through `apps/api/src/app/api/trpc/[trpc]/route.ts` to isolate routing failures.
- **Use `bun dev --inspect`** to attach Chrome DevTools or VS Code and set breakpoints in TypeScript routers like [`packages/trpc/src/router/workspace/workspace.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/router/workspace/workspace.ts).
- **Enable verbose logging** with `DEBUG=*` to see tRPC middleware execution and `DEBUG=drizzle:*` to inspect raw SQL queries.
- **Verify environment configuration** in `.env.local` against `.env.example` to resolve database connection and `env_mismatch` errors.
- **Test procedures in isolation** using `curl` or `bun test packages/trpc` to distinguish frontend bugs from backend logic errors.

## Frequently Asked Questions

### How do I enable breakpoint debugging for the Superset backend?

Use the command `bun dev --inspect --filter apps/api` to start the API with the V8 inspector enabled at `ws://127.0.0.1:9229`. Then attach Chrome DevTools via `chrome://inspect` or use the VS Code launch configuration with `"port": 9229` to set breakpoints directly in TypeScript files under `packages/trpc`.

### Why does my frontend show 404 errors for `/api/trpc` endpoints?

This occurs when the `apps/api` workspace is not running, the request URL is mistyped, or the proxy in [`apps/web/src/proxy.ts`](https://github.com/superset-sh/superset/blob/main/apps/web/src/proxy.ts) fails to match the route. Ensure you started the API with `bun dev --filter apps/api` and verify the `matcher` regex in the proxy configuration includes `/api` and `/trpc` paths.

### How can I see the SQL queries generated by the Superset backend?

Set the environment variable `DEBUG=drizzle:*` before starting the dev server: `DEBUG=drizzle:* bun dev --filter apps/api`. This outputs all generated SQL statements and their parameters to the console. Alternatively, add `console.log` statements inside the Drizzle query files in `packages/db/src`.

### What causes the `env_mismatch` warning in the desktop notifications?

The desktop notifications server ([`apps/desktop/src/main/lib/notifications/server.ts`](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/main/lib/notifications/server.ts)) emits this warning when it detects a mismatch between the expected and actual `NODE_ENV`, typically when the desktop app contacts a production backend while running in development mode. Set `SUPERSET_DEBUG_HOOKS=1` in your environment to force dev mode and suppress the warning.