Troubleshooting¶

Common issues and their solutions when working with Mavric DevEnv.

Setup Issues¶

PostgreSQL Connection Failed¶

Symptom: Backend fails to start with database connection error.

Error: connect ECONNREFUSED 127.0.0.1:5432

Solutions:

Check if PostgreSQL is running:
```
docker ps | grep postgres
```
Start PostgreSQL container:
```
docker compose up -d postgres
```

Verify connection string:

# Check .env file
cat backend/.env | grep DATABASE_URL

# Should be:
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp

Check port availability:
```
lsof -i :5432
```

Port Already in Use¶

Symptom: Server fails to start because port is occupied.

Error: listen EADDRINUSE: address already in use :::3001

Solutions:

Find process using the port:
```
lsof -i :3001
```
Kill the process:
```
kill -9 <PID>
```
Or use a different port:
```
# In backend/.env
PORT=3002
```

Missing Dependencies¶

Symptom: Module not found errors.

Error: Cannot find module '@nestjs/common'

Solutions:

Install dependencies:

cd backend && npm install
cd frontend && npm install

Clear node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

Authentication Issues¶

AUTH_SECRET Not Configured¶

Symptom: Auth fails with secret error.

Error: AUTH_SECRET environment variable is required

Solution:

Generate a secure secret and add to .env:

# Generate secret
openssl rand -base64 32

# Add to backend/.env
AUTH_SECRET=your-generated-secret-here

Session Not Persisting¶

Symptom: User gets logged out unexpectedly.

Solutions:

Check cookie settings:

// Ensure secure settings match environment
{
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax',
}

Verify CORS credentials:

app.use(cors({
  origin: 'http://localhost:3000',
  credentials: true,  // Required for cookies
}));

Check frontend fetch calls:

fetch('/api/auth/session', {
  credentials: 'include',  // Required
});

CORS Errors¶

Symptom: Browser blocks API requests.

Access to fetch at 'http://localhost:3001' from origin 'http://localhost:3000' has been blocked by CORS policy

Solution:

Configure CORS in backend:

// main.ts
app.enableCors({
  origin: process.env.CORS_ORIGIN || 'http://localhost:3000',
  credentials: true,
});

Apso Issues¶

Scaffold Command Fails¶

Symptom: apso scaffold exits with error.

Solutions:

Validate .apsorc syntax:
```
cat .apsorc | jq .
```
Check entity names:
Must be PascalCase
No reserved words
No special characters

Verify field types:

{
  "fields": {
    "name": "string",      // Valid
    "count": "number",     // Valid
    "active": "boolean",   // Valid
    "data": "object"       // Invalid - use json
  }
}

DTO Import Errors¶

Symptom: TypeScript errors about missing DTO exports.

Module '"./dtos"' has no exported member 'CreateProjectDto'

Solution:

Run the DTO fix script:

node scripts/fix-dto-imports.js

Or manually check autogen/Entity/dtos/index.ts exports.

Entity Relationship Errors¶

Symptom: Foreign key constraint failures.

Solutions:

Check relationship definitions in .apsorc:

{
  "relationships": {
    "organization": {
      "type": "many-to-one",
      "target": "Organization",
      "required": true
    }
  }
}

Ensure referenced entities exist:

# Check if Organization entity is defined
grep -l "Organization" .apsorc

Run migrations:
```
npm run typeorm migration:run
```

Database Issues¶

Migration Failures¶

Symptom: Database schema doesn't match entities.

Solutions:

Generate new migration:

npm run typeorm migration:generate -- -n UpdateSchema

Run pending migrations:
```
npm run typeorm migration:run
```

Reset database (development only):

npm run typeorm schema:drop
npm run typeorm migration:run

Duplicate Key Errors¶

Symptom: Insert fails with unique constraint violation.

Error: duplicate key value violates unique constraint

Solutions:

Check for existing data:

SELECT * FROM users WHERE email = 'test@example.com';

Handle in code:

try {
  await this.userRepo.save(user);
} catch (error) {
  if (error.code === '23505') {
    throw new ConflictError('Email already exists');
  }
  throw error;
}

Frontend Issues¶

Hydration Mismatch¶

Symptom: React hydration error in Next.js.

Error: Hydration failed because the initial UI does not match

Solutions:

Use client components for dynamic content:

'use client';

export function DynamicComponent() {
  const [mounted, setMounted] = useState(false);

  useEffect(() => {
    setMounted(true);
  }, []);

  if (!mounted) return null;

  return <div>{/* dynamic content */}</div>;
}

Suppress hydration warning (last resort):

<div suppressHydrationWarning>
  {typeof window !== 'undefined' && <DynamicContent />}
</div>

API Fetch Failures¶

Symptom: API calls fail in production but work locally.

Solutions:

Check environment variables:

# Verify NEXT_PUBLIC_ prefix for client-side vars
NEXT_PUBLIC_API_URL=https://api.example.com

Use absolute URLs in server components:

const res = await fetch(`${process.env.API_URL}/users`);

Testing Issues¶

Step Definition Not Found¶

Symptom: Cucumber can't find step implementation.

Step "I am logged in" is not defined

Solution:

Ensure step definition exists and matches:

// step-definitions/common/auth.steps.ts
import { Given } from '@cucumber/cucumber';

Given('I am logged in', async function() {
  // Implementation
});

Test Database Conflicts¶

Symptom: Tests fail due to data from other tests.

Solutions:

Use test database:

# .env.test
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/myapp_test

Clean database between tests:

beforeEach(async () => {
  await db.query('TRUNCATE users, projects CASCADE');
});

Performance Issues¶

Slow API Responses¶

Solutions:

Add database indexes:

@Entity()
@Index(['organizationId', 'status'])
export class Project {
  // ...
}

Select only needed fields:

const users = await this.userRepo.find({
  select: ['id', 'name', 'email'],
});

Use pagination:

const users = await this.userRepo.find({
  skip: (page - 1) * limit,
  take: limit,
});

N+1 Query Problem¶

Symptom: Many database queries for related data.

Solution:

Use eager loading:

// Instead of loading relations separately
const projects = await this.projectRepo.find({
  relations: ['members', 'tasks'],
});

Getting Help¶

If you can't resolve an issue:

Check logs:

# Backend logs
npm run start:dev 2>&1 | tee backend.log

# Docker logs
docker compose logs -f postgres

Enable debug mode:
```
DEBUG=* npm run start:dev
```
Search existing issues:
Check project issue tracker
Search error message online
Provide details when asking for help:
Exact error message
Steps to reproduce
Environment (OS, Node version)
Relevant log output