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

> Debug Kaneo project issues by verifying .env config, tracing HTTP exceptions in API source, and checking WebSocket logs. Your complete troubleshooting guide for the usekaneo/kaneo repo.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/lib/error-handler.ts) and the permission validation logic in [`apps/api/src/utils/validate-workspace-access.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/utils/validate-workspace-access.ts). This utility validates user roles and workspace membership, throwing `HTTPException` with specific messages when checks fail.

```typescript
// 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`](https://github.com/usekaneo/kaneo/blob/main/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:

```typescript
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`](https://github.com/usekaneo/kaneo/blob/main/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

```typescript
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

```typescript
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

```typescript
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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/ws/index.ts), configurable via Redis environment variables.
- Database migrations run automatically on API startup; check [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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.