---
title: "Troubleshooting"
description: "Troubleshooting in the Comp AI platform involves diagnosing and resolving issues across various layers, from local development environment setup to API request handling. This guide provides insight..."
last_updated: "2026-05-06T07:29:41.646098+00:00"
canonical_url: "https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/technical/section-1/troubleshooting"
---
Relevant source files
The following files were used as context for generating this wiki page:
- [README.md](https://github.com/blade47/comp/blob/main/README.md)
- [apps/api/src/common/filters/cors-exception.filter.ts](https://github.com/blade47/comp/blob/main/apps/api/src/common/filters/cors-exception.filter.ts)
- [apps/api/src/common/pipes/zod-validation.pipe.ts](https://github.com/blade47/comp/blob/main/apps/api/src/common/pipes/zod-validation.pipe.ts)
Troubleshooting in the Comp AI platform involves diagnosing and resolving issues across various layers, from local development environment setup to API request handling. This guide provides insights into common problems and their solutions, focusing on environment configuration, database management, and API error responses. Understanding these areas is crucial for maintaining a smooth development workflow and ensuring the application functions as expected.
## Local Development Environment Troubleshooting
Setting up the local development environment for Comp AI requires specific prerequisites and careful configuration of environment variables and the database. Issues in these areas are common and can prevent the application from starting or functioning correctly.
### Prerequisites and Initial Setup
Ensure your system meets the minimum software requirements before attempting to run Comp AI locally.
### Verify Prerequisites
Confirm that the following software is installed with the specified versions:
- **Node.js**: Version `>=20.x`
- **Bun**: Version `>=1.1.36`
- **Postgres**: Version `>=15.x`
If any of these are not met, update or install them accordingly.
### Clone Repository and Install Dependencies
1. Clone the Comp AI repository:
```sh
git clone https://github.com/trycompai/comp.git
```
2. Navigate to the project directory:
```sh
cd comp
```
3. Install dependencies using Bun:
```sh
bun install
```
Sources: [README.md:65-71](https://github.com/blade47/comp/blob/main/README.md#L65-L71), [README.md:83-91](https://github.com/blade47/comp/blob/main/README.md#L83-L91)
### Environment Variable Configuration
Incorrect or missing environment variables are a frequent source of issues. Comp AI requires several `.env` files to be correctly populated.
#### Required `.env` Files
Create the following `.env` files by copying from their respective `.env.example` counterparts:
- `comp/apps/app/.env`
- `comp/apps/portal/.env`
- `comp/packages/db/.env`
```sh
cp apps/app/.env.example apps/app/.env
cp apps/portal/.env.example apps/portal/.env
cp packages/db/.env.example packages/db/.env
```
```cmd
copy apps\app\.env.example apps\app\.env
copy apps\portal\.env.example apps\portal\.env
copy packages\db\.env.example apps\db\.env
```
```powershell
Copy-Item apps\app\.env.example -Destination apps\app\.env
Copy-Item apps\portal\.env.example -Destination apps\portal\.env
Copy-Item packages\db\.env.example -Destination apps\db\.env
```
#### Critical Environment Variables
Ensure `comp/apps/app/.env` contains at least the following variables:
| Variable | Description
Sources: [README.md:94-118](https://github.com/blade47/comp/blob/main/README.md#L94-L118), [README.md:120-131](https://github.com/blade47/comp/blob/main/README.md#L120-L131), [README.md:133-140](https://github.com/blade47/comp/blob/main/README.md#L133-L140)
#### Hard-coding Environment Variables
Some environment variables might not load correctly from `.env` files, especially in certain development setups or environments. In such cases, the `README.md` explicitly recommends hard-coding these values directly into the relevant source files. This should be considered a temporary troubleshooting step and ideally resolved by fixing the environment variable loading mechanism.
Specific locations for hard-coding include:
- **Google OAuth credentials**: `GOOGLE_ID`, `GOOGLE_SECRET` in `comp/apps/portal/src/app/lib/auth.ts`.
- **Redis (Upstash) credentials**: Redis URL and TOKEN in `comp/packages/kv/src/index.ts`.
- **Trigger.dev Project ID**: `project` property in `comp/apps/app/trigger.config.ts`.
Sources: [README.md:141-143](https://github.com/blade47/comp/blob/main/README.md#L141-L143), [README.md:156-158](https://github.com/blade47/comp/blob/main/README.md#L156-L158), [README.md:167-169](https://github.com/blade47/comp/blob/main/README.md#L167-L169), [README.md:176-178](https://github.com/blade47/comp/blob/main/README.md#L176-L178)
### Database Setup and Common Issues
The PostgreSQL database is a core component. Proper setup and migration are essential.
### Start Database Container
Navigate to `packages/db` and start the Docker container for PostgreSQL:
```sh
cd packages/db
bun docker:up
```
### Verify Credentials
The default credentials are:
- **Database name**: `comp`
- **Username**: `postgres`
- **Password**: `postgres`
If you need to change the password, connect to the database and run:
```sql
ALTER USER postgres WITH PASSWORD 'new_password';
```
### Resolve "No function matches..." Error
If you encounter an error message like `HINT: No function matches the given name and argument types...`, it indicates a missing database function.
To fix this, run the following command, replacing `` with your PostgreSQL password:
```sh
psql "postgresql://postgres:@localhost:5432/comp" -f ./packages/db/prisma/functionDefinition.sql
```
Expected output upon success is `CREATE FUNCTION`. Ensure you use the correct port and database name for your setup.
### Generate Prisma Client and Apply Schema
After the database is running and any function definition issues are resolved:
1. Generate the Prisma client:
```sh
bun db:generate
```
2. Push the schema to the database:
```sh
bun db:push
```
3. (Optional) Seed the database with initial data:
```sh
bun db:seed
```
#### Useful Database Commands
For further database management and troubleshooting:
- `bun db:studio`: Open Prisma Studio to view/edit data.
- `bun db:migrate`: Run database migrations.
- `bun docker:down`: Stop the database container.
- `bun docker:clean`: Remove the database container and volume.
Sources: [README.md:181-183](https://github.com/blade47/comp/blob/main/README.md#L181-L183), [README.md:185-188](https://github.com/blade47/comp/blob/main/README.md#L185-L188), [README.md:190-192](https://github.com/blade47/comp/blob/main/README.md#L190-L192), [README.md:194-203](https://github.com/blade47/comp/blob/main/README.md#L194-L203), [README.md:205-212](https://github.com/blade47/comp/blob/main/README.md#L205-L212)
## API Error Handling
The Comp AI API includes specific mechanisms to handle common errors such as Cross-Origin Resource Sharing (CORS) issues and request validation failures.
### CORS Exception Handling
The `CorsExceptionFilter` is a global exception filter designed to manage CORS headers on error responses. This is critical for allowing client applications (like the frontend) to communicate with the API, especially during development or when deployed across different domains.
#### How it Works
1. **Catches `HttpException`**: The filter intercepts any `HttpException` thrown by the API.
2. **Extracts Origin**: It reads the `Origin` header from the incoming request.
3. **Checks Allowed Origins**: It compares the request origin against a predefined list of allowed origins. This list includes:
* `http://localhost:3000`
* `http://localhost:3001`
* `http://127.0.0.1:3000`
* `https://app.trycomp.ai`
* `https://trycomp.ai`
* The value of `process.env.APP_URL`
4. **Development Mode Flexibility**: If `NODE_ENV` is not `production`, it also allows origins containing `localhost`, `127.0.0.1`, or `ngrok`.
5. **Sets CORS Headers**: If the origin is allowed, it sets `Access-Control-Allow-Origin`, `Access-Control-Allow-Credentials`, `Access-Control-Allow-Methods`, and `Access-Control-Allow-Headers` on the response.
6. **Sends Error Response**: Finally, it sends the original `HttpException`'s response body with the appropriate HTTP status code.
If you encounter CORS errors (e.g., "Access-Control-Allow-Origin header is not present") when making requests to the API, verify that your client's origin is included in the `allowedOrigins` list within the `CorsExceptionFilter` or that you are running in a development environment that permits your origin.
```typescript
// apps/api/src/common/filters/cors-exception.filter.ts
import {
ExceptionFilter,
Catch,
ArgumentsHost,
HttpException,
} from '@nestjs/common';
import type { Response, Request } from 'express';
@Catch(HttpException)
export class CorsExceptionFilter implements ExceptionFilter {
catch(exception: HttpException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse();
const request = ctx.getRequest();
const status = exception.getStatus();
const origin = request.headers.origin;
if (origin) {
const isDevelopment = process.env.NODE_ENV !== 'production';
const allowedOrigins = [
'http://localhost:3000',
'http://localhost:3001',
'http://127.0.0.1:3000',
'https://app.trycomp.ai',
'https://trycomp.ai',
process.env.APP_URL,
].filter(Boolean) as string[];
const isAllowed =
allowedOrigins.includes(origin) ||
(isDevelopment &&
(origin.includes('localhost') ||
origin.includes('127.0.0.1') ||
origin.includes('ngrok')));
if (isAllowed) {
response.setHeader('Access-Control-Allow-Origin', origin);
response.setHeader('Access-Control-Allow-Credentials', 'true');
response.setHeader(
'Access-Control-Allow-Methods',
'GET,POST,PUT,DELETE,PATCH,OPTIONS',
);
response.setHeader(
'Access-Control-Allow-Headers',
'Content-Type,Authorization,X-API-Key,X-Organization-Id',
);
}
}
response.status(status).json(exception.getResponse());
}
}
```
Sources: [apps/api/src/common/filters/cors-exception.filter.ts:1-42](https://github.com/blade47/comp/blob/main/apps/api/src/common/filters/cors-exception.filter.ts#L1-L42)
### Zod Validation Pipe
The `ZodValidationPipe` is a custom NestJS pipe used for validating incoming request data (e.g., body, query parameters) against a Zod schema. This ensures that data conforms to expected types and structures before being processed by controller handlers.
#### How it Works
1. **Constructor**: It takes a `ZodSchema` instance during its creation.
2. **`transform` Method**: When applied to a route handler parameter, this method attempts to parse the incoming `value` using the provided `schema`.
3. **Validation Failure**: If `schema.parse(value)` throws an error (meaning the data does not match the schema), the pipe catches it and throws a `BadRequestException` with the message 'Validation failed'.
Using `ZodValidationPipe` helps enforce data integrity at the API boundary, preventing malformed requests from reaching business logic. When troubleshooting, if you receive a `400 Bad Request` with the message 'Validation failed', it indicates that the request payload does not conform to the expected Zod schema for that endpoint.
```typescript
// apps/api/src/common/pipes/zod-validation.pipe.ts
import {
ArgumentMetadata,
BadRequestException,
PipeTransform,
} from '@nestjs/common';
import { ZodSchema } from 'zod';
export class ZodValidationPipe implements PipeTransform {
constructor(private schema: ZodSchema) {}
transform(value: unknown, metadata: ArgumentMetadata) {
try {
const parsedValue = this.schema.parse(value);
return parsedValue;
} catch (error) {
throw new BadRequestException('Validation failed');
}
}
}
```
Sources: [apps/api/src/common/pipes/zod-validation.pipe.ts:1-15](https://github.com/blade47/comp/blob/main/apps/api/src/common/pipes/zod-validation.pipe.ts#L1-L15)
### API Request Flow with Error Handling
The following sequence diagram illustrates how an API request is processed, including the points where CORS and Zod validation errors might be handled.
Sources: [apps/api/src/common/filters/cors-exception.filter.ts](https://github.com/blade47/comp/blob/main/apps/api/src/common/filters/cors-exception.filter.ts), [apps/api/src/common/pipes/zod-validation.pipe.ts](https://github.com/blade47/comp/blob/main/apps/api/src/common/pipes/zod-validation.pipe.ts)
## Sitemap
See the full [sitemap](https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/llms.txt) for all pages in this wiki.