> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselumina.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

## Traces Not Appearing

**Check endpoint:**

```typescript theme={null}
// Correct
endpoint: 'http://localhost:9411/v1/traces'

// Wrong
endpoint: 'http://localhost:8081' // This is query API
```

**Check ingestion logs:**

```bash theme={null}
docker compose logs ingestion | grep ERROR
```

**Test with cURL:**

```bash theme={null}
curl -X POST http://localhost:9411/v1/traces \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans":[...]}'
```

***

## High Memory Usage

**Increase PostgreSQL memory:**

```sql theme={null}
ALTER SYSTEM SET shared_buffers = '8GB';
ALTER SYSTEM SET work_mem = '128MB';
```

**Enable sampling:**

```typescript theme={null}
const lumina = initLumina({
  endpoint: 'http://lumina:9411/v1/traces',
  service_name: 'service',
  samplingRate: 0.1,
});
```

**Configure retention:**

```bash theme={null}
TRACE_RETENTION_DAYS=7
```

***

## Slow Queries

**Add indexes:**

```sql theme={null}
CREATE INDEX CONCURRENTLY idx_traces_service
ON traces (service_name);

CREATE INDEX CONCURRENTLY idx_traces_cost
ON traces (cost_usd) WHERE cost_usd > 0.01;
```

**Enable caching:**

```bash theme={null}
ENABLE_QUERY_CACHE=true
```

***

## Port Conflicts

**Change ports:**

```bash theme={null}
# .env
DASHBOARD_PORT=3001
API_PORT=8082
INGESTION_PORT=9412
```

**Find conflicting process:**

```bash theme={null}
lsof -i :3000
kill -9 <PID>
```

***

## Database Connection Failed

**Wait for PostgreSQL:**

```bash theme={null}
docker compose logs postgres | grep "ready to accept connections"
```

**Restart services:**

```bash theme={null}
docker compose restart ingestion api
```

**Check connection string:**

```bash theme={null}
DATABASE_URL=postgres://user:password@localhost:5432/lumina
```

***

## Need More Help?

* [GitHub Discussions](https://github.com/use-lumina/Lumina/discussions)
* [GitHub Issues](https://github.com/use-lumina/Lumina/issues)
* [Email Support](mailto:support@uselumina.io)