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:

# 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:

docker compose logs [service_name]

Common Causes:

Missing environment variables

Check that all required variables are set in your .env file:

# 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

Port conflicts

Another service may be using the required ports.

# 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.

Docker image access

Ensure you’re authenticated to pull the Bilanc image:

gcloud auth configure-docker europe-west2-docker.pkg.dev

If you see permission errors, contact Bilanc support to verify your access.

---

Database Connection Issues

Cannot Connect to PostgreSQL

Symptoms: API or Dagster fails with database connection errors.

Diagnosis:

docker compose logs api | grep -i "postgres\|database"

Solutions:

Verify database credentials

Check your .env file:

POSTGRES_HOST=your_host
POSTGRES_PORT=5432
POSTGRES_DATABASE=bilanc
POSTGRES_USERNAME=your_user
POSTGRES_PASSWORD=your_password

Test the connection manually:

psql -h $POSTGRES_HOST -U $POSTGRES_USERNAME -d $POSTGRES_DATABASE

Network connectivity

If using an external database, ensure the Docker containers can reach it:

docker compose exec api ping your_postgres_host

For cloud databases, check security groups/firewall rules.

Docker networking

If using the bundled PostgreSQL, ensure services are on the same network:

docker network ls
docker network inspect docker_network

---

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

# 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

# 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:

# Check Dagster daemon is running
docker compose ps dagster_daemon

# View daemon logs
docker compose logs -f dagster_daemon

Solutions:

Check schedule status

Open Dagster UI at http://localhost:4000 and verify schedules are enabled.

Restart Dagster

docker compose restart dagster_daemon dagster_webserver

Pipeline Failures

Symptoms: Pipelines start but fail partway through.

Diagnosis:

1. Open Dagster UI at 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:

docker compose logs -f api

Common Causes:

Database connection lost

Restart the API service:

docker compose restart api

Memory issues

Check container memory usage:

docker stats api

Increase memory allocation if needed.

API Health Check

# 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.

Diagnosis:

docker compose logs -f frontend

Solutions:

Check API connectivity

The dashboard needs to reach the API:

# From the frontend container
docker compose exec frontend curl http://api:8000/health

Environment variables

Verify NEXT_PUBLIC_API_URL is set correctly for your deployment.

---

Email Issues

Emails Not Sending

Symptoms: Scheduled reports or notifications not arriving.

Diagnosis:

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:

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

# 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:

# 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:

   docker compose logs > bilanc-logs.txt
   

2. Check configuration:

   # Anonymize sensitive values before sharing
   cat .env | sed 's/=.*/=REDACTED/'
   

3. Contact support: Email [e-mail] with:

   • Description of the issue
   • Steps to reproduce
   • Relevant log excerpts
   • Your configuration (with secrets redacted)