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

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

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:

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

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

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:

bun dev --filter apps/api

Enable the V8 inspector for breakpoint debugging:

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:

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

For maximum verbosity across all libraries:

DEBUG=* bun dev --filter apps/api

Testing Endpoints with cURL

Reproduce exact API calls without the frontend to isolate issues:

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:

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 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 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 forwards the request correctly.
tRPC "Method not found"	Procedure name typo or router not exported in 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) 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, 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.

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.

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