# How to Debug the Apache Superset Backend: A Complete Guide to tRPC API Troubleshooting

> Debug Apache Superset backend by attaching the Node.js inspector to the tRPC API server. Trace requests and add console logs to effectively troubleshoot your Superset API.

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

---

**You can debug the Apache Superset backend by attaching the Node.js inspector to the tRPC API server, adding strategic `console.log` statements in router procedures, and tracing requests through the entry point at `apps/api/src/app/api/trpc/[trpc]/route.ts` down to the business logic layer.**

The Superset backend is built as a **tRPC-powered API** running inside a Next.js/Node environment within the `apps/api` workspace. Whether you are troubleshooting failed API calls, database connection issues, or authentication errors, understanding how to effectively debug Apache Superset backend components will save hours of development time.

## Understanding the Superset Backend Architecture

Before diving into debugging techniques, you need to understand the three-tier architecture of the Superset backend:

- **Entry Point**: The Next.js route handler at `apps/api/src/app/api/trpc/[trpc]/route.ts` receives all incoming HTTP requests and forwards them to the tRPC handler.
- **Router Layer**: The root router at [`packages/trpc/src/root.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/root.ts) composes all sub-routers (workspace, project, agent) into a single `appRouter` object.
- **Business Logic Layer**: Individual procedures in `packages/trpc/src/router/<name>/` call services, interact with the Drizzle ORM schema in `packages/db/src/schema/`, or trigger desktop notifications via [`apps/desktop/src/main/lib/notifications/server.ts`](https://github.com/superset-sh/superset/blob/main/apps/desktop/src/main/lib/notifications/server.ts).

## Three-Layer Debugging Approach for the Superset Backend

When you debug Apache Superset backend issues, work systematically through these three layers to isolate the failure point.

### Layer 1: Entry Point and Routing Verification

Start by confirming that requests actually reach the tRPC handler. The entry point lives in `apps/api/src/app/api/trpc/[trpc]/route.ts`. If this file fails to load due to syntax errors or missing imports, the dev server will log the issue immediately upon startup.

Check the console output when running:

```bash
bun dev --filter apps/api

```

If you see `404 Not Found` on `/api/trpc/...` endpoints, verify that the Next.js dev server is running on the expected port (default `3000` as defined in `.env.example`) and that the file path matches the dynamic route pattern `[trpc]`.

### Layer 2: Router and Procedure Inspection

Once routing is confirmed, identify which tRPC router handles your request. All routers are composed in [`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>/`.

To inspect runtime values, add `console.log` or `debugger` statements inside the desired procedure. For example, in [`packages/trpc/src/router/workspace/workspace.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/router/workspace/workspace.ts):

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

```

The output appears in the terminal where `bun dev` is running. When using the `--inspect` flag, the `debugger` statement pauses execution for step-through analysis in Chrome DevTools or VS Code.

### Layer 3: Business Logic and Side Effects

Complex issues often reside in the services or external integrations called by procedures. Common places to inspect include the notification hook server at [`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 any data-access layer under `packages/db`.

To trace database queries, enable Drizzle logging by setting `DEBUG=drizzle:*` or adding explicit logging in your query files:

```bash
DEBUG=drizzle:* bun dev --filter apps/api

```

This outputs generated SQL and parameters to the console, helping you identify schema mismatches or slow queries.

## Practical Debugging Workflows and Commands

Use these specific commands and techniques to debug Apache Superset backend issues efficiently.

### Starting the API with Debug Options

Run only the API workspace to isolate backend issues:

```bash
bun dev --filter apps/api

```

Enable the V8 inspector for breakpoint debugging:

```bash
bun dev --inspect --filter apps/api

```

This opens the inspector at `ws://127.0.0.1:9229`. Open Chrome at `chrome://inspect` to attach DevTools and set breakpoints directly in TypeScript sources.

### Increasing Log Verbosity

Set the `DEBUG` environment variable to see tRPC internal messages:

```bash
DEBUG=trpc:* bun dev --filter apps/api

```

For maximum verbosity across all libraries:

```bash
DEBUG=* bun dev --filter apps/api

```

### Testing Endpoints with cURL

Reproduce exact API calls without the frontend to isolate issues:

```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` prints the stack trace and request payload to the console.

### Running Backend Unit Tests

Verify procedure logic in isolation:

```bash
bun test packages/trpc

```

This runs tests against the tRPC routers without starting the full HTTP server, making it ideal for debugging business logic quickly.

### VS Code Launch Configuration

Create [`.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 press F5 to start debugging.

## Common Superset Backend Debugging Issues and Fixes

| Symptom | Likely Cause | Fix |
|---------|--------------|-----|
| **404 Not Found on `/api/trpc/...`** | The dev server isn't running the `apps/api` workspace, or the route path is mistyped. | Run `bun dev --filter apps/api` or ensure the `matcher` in [`apps/web/src/proxy.ts`](https://github.com/superset-sh/superset/blob/main/apps/web/src/proxy.ts) forwards the request correctly. |
| **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's 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)) is contacting 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 or mismatched environment variables (`DATABASE_URL`, `NEON_PROJECT_ID`). | Copy `.env.example` to `.env.local` and fill in required values; the server reads them via `shared/env.shared`. |
| **Long-running request hangs** | Unhandled promise in a procedure (e.g., missing `await`). | Add proper `await`/`try…catch` blocks and log errors to identify the hanging operation. |

## Summary

To effectively debug Apache Superset backend issues, remember these key strategies:

- **Isolate the API** by running `bun dev --filter apps/api` to eliminate frontend interference.
- **Trace the request flow** through three layers: the entry point at `apps/api/src/app/api/trpc/[trpc]/route.ts`, the router composition in [`packages/trpc/src/root.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/root.ts), and the specific procedure logic.
- **Use Node.js debugging tools** by starting the server with `--inspect` and attaching Chrome DevTools or VS Code to set breakpoints in TypeScript source files.
- **Enable verbose logging** with `DEBUG=*` or `DEBUG=trpc:*` to see internal tRPC operations and database queries.
- **Test procedures directly** using `curl` or unit tests (`bun test packages/trpc`) to reproduce issues without the full UI stack.

## Frequently Asked Questions

### How do I attach a debugger to the running Superset backend?

Start the API with the inspect flag using `bun dev --inspect --filter apps/api`, then open Chrome DevTools at `chrome://inspect` or configure VS Code with a Node.js attach configuration targeting port `9229`. You can then set breakpoints directly in files like [`packages/trpc/src/router/workspace/workspace.ts`](https://github.com/superset-sh/superset/blob/main/packages/trpc/src/router/workspace/workspace.ts).

### Why am I getting a 404 error on `/api/trpc` endpoints?

A 404 usually indicates that the `apps/api` workspace is not running, the Next.js route file at `apps/api/src/app/api/trpc/[trpc]/route.ts` has a syntax error preventing it from loading, or the request path is misspelled. Verify the server is running with `bun dev --filter apps/api` and check the console for startup errors.

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

Set the environment variable `DEBUG=drizzle:*` when starting the server: `DEBUG=drizzle:* bun dev --filter apps/api`. This outputs all generated SQL statements and their parameters to the console, helping you identify slow queries or schema mismatches in the Drizzle ORM layer under `packages/db`.

### What is the fastest way to test a specific tRPC procedure without the frontend?

Use `curl` to send a POST request directly to the procedure endpoint. For example: `curl -X POST http://localhost:3000/api/trpc/workspace.getDetails -H "Content-Type: application/json" -d '{"json":{"workspaceId":"wrk_123"}}'`. Alternatively, run unit tests with `bun test packages/trpc` to verify procedure logic in isolation.