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

# Troubleshooting

> Common issues and solutions for self-hosted Bilanc.

This guide covers common issues you might encounter when running self-hosted Bilanc and how to resolve them.

## Quick Diagnostics

Before diving into specific issues, run these commands to gather diagnostic information:

```bash theme={null}
# Check container status
docker compose ps

# View recent logs
docker compose logs --tail 50

# Check resource usage
docker stats --no-stream
```

***

## Container Startup Issues

### Containers Fail to Start

**Symptoms**: Containers exit immediately or restart repeatedly.

**Diagnosis**:

```bash theme={null}
docker compose logs [service_name]
```

**Common Causes**:

<Accordion title="Missing environment variables">
  Check that all required variables are set in your `.env` file:

  ```bash theme={null}
  # Verify .env exists
  ls -la .env

  # Check for empty values
  grep -E "^[A-Z_]+=\s*$" .env
  ```

  Ensure these critical variables are set:

  * `POSTGRES_PASSWORD`
  * `AI_PROVIDER` and corresponding API key
  * `GITHUB_ACCESS_TOKEN`
</Accordion>

<Accordion title="Port conflicts">
  Another service may be using the required ports.

  ```bash theme={null}
  # Check if ports are in use
  lsof -i :3000  # Dashboard
  lsof -i :8000  # API
  lsof -i :4000  # Dagster
  lsof -i :6379  # Redis
  ```

  Stop conflicting services or change the ports in `docker-compose.yml`.
</Accordion>

<Accordion title="Docker image access">
  Ensure you're authenticated to pull the Bilanc image:

  ```bash theme={null}
  gcloud auth configure-docker europe-west2-docker.pkg.dev
  ```

  If you see permission errors, contact Bilanc support to verify your access.
</Accordion>

***

## Database Connection Issues

### Cannot Connect to PostgreSQL

**Symptoms**: API or Dagster fails with database connection errors.

**Diagnosis**:

```bash theme={null}
docker compose logs api | grep -i "postgres\|database"
```

**Solutions**:

<Accordion title="Verify database credentials">
  Check your `.env` file:

  ```bash theme={null}
  POSTGRES_HOST=your_host
  POSTGRES_PORT=5432
  POSTGRES_DATABASE=bilanc
  POSTGRES_USERNAME=your_user
  POSTGRES_PASSWORD=your_password
  ```

  Test the connection manually:

  ```bash theme={null}
  psql -h $POSTGRES_HOST -U $POSTGRES_USERNAME -d $POSTGRES_DATABASE
  ```
</Accordion>

<Accordion title="Network connectivity">
  If using an external database, ensure the Docker containers can reach it:

  ```bash theme={null}
  docker compose exec api ping your_postgres_host
  ```

  For cloud databases, check security groups/firewall rules.
</Accordion>

<Accordion title="Docker networking">
  If using the bundled PostgreSQL, ensure services are on the same network:

  ```bash theme={null}
  docker network ls
  docker network inspect docker_network
  ```
</Accordion>

***

## Integration Issues

### GitHub: 401 Unauthorized

**Symptoms**: GitHub pipeline fails with authentication errors.

**Solutions**:

1. **Token expired**: Generate a new Personal Access Token
2. **Insufficient scopes**: Ensure token has `repo` and `read:org` scopes
3. **No repository access**: Verify token owner has access to listed repositories

```bash theme={null}
# Test your token
curl -H "Authorization: token $GITHUB_ACCESS_TOKEN" \
  https://api.github.com/user
```

### GitHub: No Data Appearing

**Symptoms**: Pipelines run successfully but no data in dashboard.

**Check**:

1. Verify `GITHUB_REPOSITORY` format is correct (`owner/repo`)
2. Check the `start_date` in `tenant_config.yaml` isn't in the future
3. Ensure there's activity in the repositories within the date range

### Linear: No Data

**Symptoms**: Linear pipeline runs but no issues appear.

**Solutions**:

1. Verify API token is correct
2. Check token owner has access to the workspace
3. Ensure `start_date` covers the period with issue activity

```bash theme={null}
# Test your Linear token
curl -H "Authorization: $LINEAR_ACCESS_TOKEN" \
  https://api.linear.app/graphql \
  -d '{"query": "{ viewer { id name } }"}'
```

### Cursor: Connection Failed

**Symptoms**: Cursor pipeline fails to connect.

**Solutions**:

1. Verify `CURSOR_API_KEY` is correct
2. Contact Bilanc support if the issue persists

***

## Pipeline Issues

### Pipelines Not Running

**Symptoms**: No data being ingested, Dagster shows no runs.

**Diagnosis**:

```bash theme={null}
# Check Dagster daemon is running
docker compose ps dagster_daemon

# View daemon logs
docker compose logs -f dagster_daemon
```

**Solutions**:

<Accordion title="Check schedule status">
  Open Dagster UI at [http://localhost:4000](http://localhost:4000) and verify schedules are enabled.
</Accordion>

<Accordion title="Restart Dagster">
  ```bash theme={null}
  docker compose restart dagster_daemon dagster_webserver
  ```
</Accordion>

### Pipeline Failures

**Symptoms**: Pipelines start but fail partway through.

**Diagnosis**:

1. Open Dagster UI at [http://localhost:4000](http://localhost:4000)
2. Click on the failed run
3. Expand the failed step to see error details

**Common Causes**:

* API rate limits (wait and retry)
* Invalid credentials (check tokens)
* Network timeouts (check connectivity)

***

## API Issues

### API Returns 500 Errors

**Symptoms**: Dashboard shows errors, API requests fail.

**Diagnosis**:

```bash theme={null}
docker compose logs -f api
```

**Common Causes**:

<Accordion title="Database connection lost">
  Restart the API service:

  ```bash theme={null}
  docker compose restart api
  ```
</Accordion>

<Accordion title="Memory issues">
  Check container memory usage:

  ```bash theme={null}
  docker stats api
  ```

  Increase memory allocation if needed.
</Accordion>

### API Health Check

```bash theme={null}
# Check if API is responding
curl http://localhost:8000/health

# Expected response: {"status": "healthy"}
```

***

## Dashboard Issues

### Dashboard Not Loading

**Symptoms**: Browser shows error or blank page at [http://localhost:3000](http://localhost:3000).

**Diagnosis**:

```bash theme={null}
docker compose logs -f frontend
```

**Solutions**:

<Accordion title="Check API connectivity">
  The dashboard needs to reach the API:

  ```bash theme={null}
  # From the frontend container
  docker compose exec frontend curl http://api:8000/health
  ```
</Accordion>

<Accordion title="Environment variables">
  Verify `NEXT_PUBLIC_API_URL` is set correctly for your deployment.
</Accordion>

***

## Email Issues

### Emails Not Sending

**Symptoms**: Scheduled reports or notifications not arriving.

**Diagnosis**:

```bash theme={null}
docker compose logs -f worker | grep -i "email\|resend"
```

**Solutions**:

1. Verify `RESEND_API_KEY` is correct
2. Check `DEFAULT_SENDER_EMAIL` is a valid sender in Resend
3. Verify the sender domain is configured in Resend

***

## AI Insights Issues

### AI Insights Not Generating

**Symptoms**: Insights section is empty or shows errors.

**Diagnosis**:

```bash theme={null}
docker compose logs -f worker | grep -i "ai\|openai\|anthropic\|google"
```

**Solutions**:

1. Verify `AI_PROVIDER` is set to a valid value (`openai`, `anthropic`, `google-ai`)
2. Check the corresponding API key is set and valid
3. Ensure you have API credits/quota remaining

```bash theme={null}
# Test OpenAI connection
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"
```

***

## Performance Issues

### Slow Dashboard

**Symptoms**: Dashboard takes long to load or times out.

**Solutions**:

1. **Scale PostgreSQL**: Increase CPU/RAM for the database
2. **Check indexes**: Ensure database has proper indexes
3. **Reduce data range**: Use shorter time ranges in queries

### High Memory Usage

**Symptoms**: Containers being killed or system running slow.

**Solutions**:

```bash theme={null}
# Check memory usage
docker stats

# Increase container limits in docker-compose.yml
# services:
#   api:
#     deploy:
#       resources:
#         limits:
#           memory: 4G
```

***

## Getting Help

If you're still experiencing issues:

1. **Collect logs**:
   ```bash theme={null}
   docker compose logs > bilanc-logs.txt
   ```

2. **Check configuration**:
   ```bash theme={null}
   # Anonymize sensitive values before sharing
   cat .env | sed 's/=.*/=REDACTED/'
   ```

3. **Contact support**: Email [support@bilanc.co](mailto:support@bilanc.co) with:
   * Description of the issue
   * Steps to reproduce
   * Relevant log excerpts
   * Your configuration (with secrets redacted)