How to Debug Issues in the Kaneo Project: A Complete Troubleshooting Guide

Debugging Kaneo requires verifying the shared .env configuration, tracing HTTPException errors through the API source, and checking WebSocket adapter initialization logs.

Kaneo is a self-hosted project management platform built as a pnpm monorepo with a Hono API backend and React frontend. When you debug issues in the Kaneo project, you are typically working across two runtimes that share a single environment configuration. Understanding the specific error handling patterns in apps/web/src/lib/error-handler.ts and the permission validation logic in apps/api/src/utils/validate-workspace-access.ts will help you isolate failures quickly.

Common Failure Points and Diagnostic Locations

Most production issues in Kaneo fall into five specific categories. Each has distinct symptoms and corresponding source files where errors originate.

CORS and Network Errors

If you see "Failed to fetch" or "CORS" errors in the browser console, the frontend has already categorized the error via parseApiError in apps/web/src/lib/error-handler.ts. This helper analyzes network-related failures and returns structured error types.

The getCorsTroubleshootingSteps() function provides exact checks you should perform when error.message contains network failure strings. Check that KANEO_API_URL and KANEO_CLIENT_URL in your .env file use correct protocols and ports.

Database Connection Failures

When the API fails to start with "Database connection failed" messages, examine apps/api/src/database/* and the startup logs in apps/api/src/index.ts. The application automatically runs migrations on startup from apps/api/src/migrations/, and any failure here aborts the server launch.

Verify your DATABASE_URL format and the derived POSTGRES_* variables. The connection string must be valid before the Hono server begins accepting requests.

Authentication and Permission Errors

401 Unauthorized or 403 Forbidden responses originate from apps/api/src/utils/validate-workspace-access.ts. This utility validates user roles and workspace membership, throwing HTTPException with specific messages when checks fail.

// apps/api/src/utils/validate-workspace-access.ts
if (membership.length === 0) {
  throw new HTTPException(403, { message: "You don't have access to this workspace" });
}

These exceptions surface as JSON responses that you can inspect in your browser's Network tab.

WebSocket Broadcasting Issues

Missing real-time updates indicate problems with the broadcast adapter initialized in apps/api/src/ws/index.ts. The system implements both in-memory and Redis adapters selected by isRedisConfigured().

When the API starts, it logs the active adapter:

console.log(`📡 WebSockets Initialized using: "${adapter.constructor.name}"`);

If using Redis, confirm REDIS_URL, REDIS_SENTINELS, or REDIS_CLUSTER_NODES are set correctly in your environment.

MCP and External Integration Failures

MCP commands and webhook integrations fail when endpoints in apps/api/src/mcp/* or apps/api/src/*-integration/* throw HTTPException errors. Verify that /api/mcp/health returns a successful response and that webhook secrets match the configured values in your .env file.

Step-by-Step Debugging Workflow

Follow this systematic approach to isolate and resolve issues when debugging Kaneo.

1. Verify Environment Configuration

   Ensure .env contains all required variables including KANEO_CLIENT_URL, KANEO_API_URL, AUTH_SECRET, and DATABASE_URL. Refer to the ENVIRONMENT_SETUP.md guide for the complete variable list.

2. Start Services and Monitor Logs

   Run pnpm dev and watch console output. The API prints its configuration on startup, while the web app logs the Vite dev server address. Look for migration status messages in the API terminal.

3. Check Browser Developer Tools

   Open DevTools and examine the Console and Network tabs. If you see "Failed to fetch" errors, the frontend has already processed them through parseApiError with specific type categorization.

4. Trace API Error Paths

   Search for HTTPException throws in the API codebase. These exceptions carry specific status codes and messages that appear in network response bodies. Breakpoints around validateWorkspaceAccess calls reveal permission logic failures.

5. Inspect WebSocket Initialization

   Confirm the broadcast adapter logged during startup matches your infrastructure. If you expect Redis but see "InMemoryAdapter", check your REDIS_* environment variables.

6. Validate Database State

   Connect to your PostgreSQL instance and verify migration tables exist. Failed migrations leave the database in partial states that prevent API startup.

7. Test Endpoints in Isolation

   Spin up only the API using pnpm --filter @kaneo/api dev and test endpoints with curl or Postman. This eliminates frontend variables when debugging backend logic.

8. Check Integration Connectivity

   For MCP or webhook issues, verify external services can reach your API. Use tools like ngrok for local webhook testing and confirm signature validation logic in the integration handlers.

9. Add Strategic Logging

   Insert console.log statements in TypeScript hooks like useTaskFilters or useProjectWebsocket on the frontend, or use node --inspect for backend debugging around suspect code paths.

Essential Debugging Code Patterns

Use these patterns when implementing error handling or investigating issues in your Kaneo instance.

Parsing Frontend API Errors

import { parseApiError, getCorsTroubleshootingSteps } from "@/lib/error-handler";

try {
  const res = await fetch("/api/task");
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  // Process response
} catch (e) {
  const err = parseApiError(e);
  console.warn(err.message);
  if (err.type === "cors") {
    console.table(getCorsTroubleshootingSteps());
  }
}

Validating Workspace Access

import { validateWorkspaceAccess } from "@/utils/validate-workspace-access";

export async function someProtectedHandler(c) {
  const userId = c.get("userId");
  const workspaceId = c.req.param("workspaceId");
  await validateWorkspaceAccess(userId, workspaceId); // Throws 403 if not allowed
  // Authorized logic continues
}

Broadcasting Project Events

import { broadcastToProject } from "@/ws";

broadcastToProject(projectId, {
  type: "TASK_UPDATED",
  taskId,
  changes: { status: "done" },
});

Summary

• Kaneo uses a shared .env file for both API and web runtimes; incorrect variables cause most deployment issues.
• Frontend network errors are categorized in apps/web/src/lib/error-handler.ts with specific troubleshooting steps for CORS failures.
• API permission errors originate from apps/api/src/utils/validate-workspace-access.ts and throw descriptive HTTPException instances.
• Real-time features depend on the WebSocket adapter selected at runtime in apps/api/src/ws/index.ts, configurable via Redis environment variables.
• Database migrations run automatically on API startup; check apps/api/src/index.ts logs for connection failures.

Frequently Asked Questions

Why am I seeing CORS errors when connecting to the Kaneo API?

CORS errors appear when KANEO_CLIENT_URL and KANEO_API_URL in your .env file use mismatched protocols or ports. The parseApiError function in apps/web/src/lib/error-handler.ts specifically detects these failures and provides troubleshooting steps. Ensure your API server allows requests from your frontend origin and that both services use the correct URL values defined in the environment setup guide.

How do I fix database connection failures in Kaneo?

Database failures occur when the API cannot connect to PostgreSQL using the DATABASE_URL variable. Check the startup logs in apps/api/src/index.ts for connection string errors and verify your PostgreSQL server is running. The API automatically runs migrations from apps/api/src/migrations/ on startup, so ensure the database user has schema modification permissions.

Why are real-time updates not working in my Kaneo instance?

Real-time updates depend on the WebSocket broadcast adapter initialized in apps/api/src/ws/index.ts. Check the API startup logs for the line indicating which adapter is active. If you configured Redis but see "InMemoryAdapter", verify that REDIS_URL or cluster/sentinel variables are set correctly. The broadcastToProject function requires the correct adapter to propagate events to connected clients.

How do I debug authentication loops or 403 errors?

Authentication issues originate from apps/api/src/utils/validate-workspace-access.ts, which validates user membership against workspace IDs. When debugging, inspect the Network tab for HTTPException responses containing specific messages like "You don't have access to this workspace". Ensure your AUTH_SECRET is consistent across restarts and that the user record exists in the database with valid workspace associations.

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