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

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) 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) 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 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. 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) 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 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.	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) 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:

# 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 at runtime.

Adding Debug Statements to tRPC Procedures

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

// 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:

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 for integrated debugging:

{
  "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	Combines all sub-routers (workspace, project, agent) into a single appRouter that defines the API surface.
tRPC Initialization	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	Example CRUD router showing how procedures access the database and handle frontend requests.
Frontend Proxy	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	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 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.
• 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 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) 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.

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