Troubleshooting

Active Development

Aether is under rapid development. If you encounter an issue not listed here, check the backend logs first (docker-compose logs -f goway) and open a GitHub issue if it looks like a bug.

Common issues and their solutions.

Database Issues

Connection Refused

Symptom:

Failed to connect to database: dial tcp 127.0.0.1:5432: connect: connection refused

Causes:

PostgreSQL not running
Wrong host in DATABASE_URL
Docker network issues

Solutions:

bash

# 1. Check if PostgreSQL is running
docker-compose ps postgres

# 2. Start PostgreSQL if stopped
docker-compose up -d postgres

# 3. Wait for healthy status
docker-compose ps  # Should show "healthy"

# 4. Verify connection string
echo $DATABASE_URL
# Should be localhost:5432 for local dev, postgres:5432 in Docker

# 5. Test connection directly
psql $DATABASE_URL -c "SELECT 1;"

Authentication Failed

Symptom:

password authentication failed for user "postgres"

Solutions:

bash

# Check credentials in DATABASE_URL match docker-compose.yml
# Default: postgres:postgres

# Reset if needed
docker-compose down -v  # Warning: deletes data
docker-compose up -d postgres

Dirty Migration State

Symptom:

Dirty database version 17. Fix and force version.

Solutions:

bash

cd goway

# 1. Check current state
psql $DATABASE_URL -c "SELECT * FROM schema_migrations;"

# 2. Examine the failed migration
cat migrations/000017_*.up.sql

# 3. Option A: Fix manually and force version
psql $DATABASE_URL -c "<fix commands>"
migrate -path migrations -database "$DATABASE_URL" force 17

# 3. Option B: Rollback and retry
migrate -path migrations -database "$DATABASE_URL" force 16
make migrate-up

LLM Service Issues

Service Unavailable

Symptom:

LLM service not available

Failed to connect to LLM: connection refused

Solutions:

bash

# 1. Check LiteLLM status
curl http://localhost:4000/health

# 2. Check container logs
docker-compose logs litellm

# 3. Restart LiteLLM
docker-compose restart litellm

# 4. Verify configuration
# Check litellm_config.yaml exists and is valid

# 5. Check LLM_BASE_URL
# Local dev: http://localhost:4000
# Docker: http://litellm:4000

Model Not Found

Symptom:

Model 'ollama/phi4' not found

Solutions:

bash

# 1. Check available models in litellm_config.yaml

# 2. If using Ollama, ensure model is pulled
ollama pull phi4

# 3. Verify LLM_MODEL environment variable
echo $LLM_MODEL

Rate Limiting / API Errors

Symptom:

Rate limit exceeded

Invalid API key

Solutions:

bash

# 1. Check API keys in environment or litellm_config.yaml
# OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.

# 2. Verify key is valid
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# 3. Check LiteLLM logs for details
docker-compose logs litellm | tail -50

Issue Tracker Issues

Updates Not Posting

Symptom: Agent responses not appearing on GitHub/GitLab/Plane/Jira issues.

Solutions:

bash

# 1. Check if tracker updates are enabled
echo $TRACKER_UPDATES_ENABLED  # Should be "true"

# 2. Verify token is set
echo $GITHUB_TOKEN    # For GitHub
echo $GITLAB_TOKEN    # For GitLab
echo $PLANE_API_KEY   # For Plane
echo $JIRA_API_TOKEN  # For Jira

# 3. Check token permissions
# GitHub: needs 'repo' or 'public_repo' scope
# GitLab: needs 'api' scope
# Jira Cloud: needs proper API token
# Jira Server: needs correct username/password

# 4. Check server logs for errors
docker-compose logs goway | grep -i "tracker\|github\|gitlab\|plane\|jira"

# 5. Test token manually
# GitHub:
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user

# GitLab:
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  $GITLAB_URL/api/v4/user

# Jira Cloud:
curl -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
  $JIRA_URL/rest/api/3/myself

Webhook Not Received

Symptom: Webhooks from external services not triggering processing.

Solutions:

bash

# 1. Check webhook endpoint is accessible
curl -X POST http://localhost:8000/webhook/github \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# 2. Check server logs
docker-compose logs goway | tail -50

# 3. Verify webhook configuration in external service
# - URL should be: https://your-domain/webhook/{source}
# - Content type: application/json
# - For production, use HTTPS

# 4. If using ngrok or tunnel, verify it's running
ngrok http 8000

# 5. Check "Recent Deliveries" in webhook settings
# GitHub: Repository Settings → Webhooks → Recent Deliveries
# GitLab: Project Settings → Webhooks → Recent Events

NATS Issues

Connection Failed

Symptom:

Failed to connect to NATS - events will not be published

Solutions:

bash

# 1. Check NATS is running
docker-compose ps nats

# 2. Start if needed
docker-compose up -d nats

# 3. Verify URL
echo $NATS_URL
# Local: nats://localhost:4222
# Docker: nats://nats:4222

# 4. Test connection
# Visit http://localhost:8222 for NATS monitoring

INFO

NATS connection failure is a warning, not fatal. The system continues without event publishing.

Frontend Issues

API Connection Failed

Symptom: Frontend shows "Network Error" or fails to load data.

Solutions:

bash

# 1. Verify backend is running
curl http://localhost:8000/health

# 2. Check CORS configuration
# Backend should allow frontend origin

# 3. Check browser console for specific errors
# Look for CORS errors or 404s

# 4. Verify API URL in frontend config
# Check web/src/services/ for API base URL
# Should be http://localhost:8000 for dev

Build Failures

Symptom:

npm run build fails with type errors

Solutions:

bash

cd web

# 1. Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# 2. Check for TypeScript errors
npm run build 2>&1 | head -50

# 3. Run lint to find issues
npm run lint

Docker Issues

Container Won't Start

Symptom: Container exits immediately or keeps restarting.

Solutions:

bash

# 1. Check container logs
docker-compose logs goway

# 2. Check container status
docker-compose ps -a

# 3. Common causes:
# - Missing required environment variable
# - Database not ready (check depends_on health checks)
# - Port already in use
# - Configuration error

# 4. Rebuild if needed
docker-compose build --no-cache goway
docker-compose up -d

Port Already in Use

Symptom:

Bind for 0.0.0.0:8000 failed: port is already allocated

Solutions:

bash

# 1. Find what's using the port
lsof -i :8000

# 2. Kill the process or change port
# Option A: Kill process
kill -9 <PID>

# Option B: Change port in .env
PORT=8001

# Option C: Change in docker-compose.yml
ports:
  - "8001:8000"

Out of Disk Space

Symptom:

no space left on device

Solutions:

bash

# 1. Clean up Docker resources
docker system prune -a

# 2. Remove unused volumes
docker volume prune

# 3. Check disk usage
df -h
docker system df

# 4. Remove old images
docker images
docker rmi <image-id>

Performance Issues

Slow Startup

Symptom: Server takes a long time to start.

Causes:

Many pending migrations
Database connection delays
LLM health checks timing out

Solutions:

bash

# 1. Pre-warm database connection
docker-compose up -d postgres
sleep 10
docker-compose up -d goway

# 2. Check migration count
ls goway/migrations/*.up.sql | wc -l

# 3. Reduce health check frequency in docker-compose.yml
healthcheck:
  interval: 10s  # Increase from 5s

High Memory Usage

Symptom: Container using excessive memory.

Solutions:

bash

# 1. Check container stats
docker stats

# 2. Set memory limits in docker-compose.yml
services:
  goway:
    deploy:
      resources:
        limits:
          memory: 512M

# 3. Optimize database connection pool
# Reduce pool size in DATABASE_URL:
# ?pool_max_conns=10

Agent Responses Slow

Symptom: Agent takes a long time to respond to webhooks.

Causes:

LLM provider latency
Large context being sent
Network issues

Solutions:

bash

# 1. Check LLM provider status
# OpenAI: https://status.openai.com
# Anthropic: https://status.anthropic.com

# 2. Use faster models
# Change LLM_MODEL to gpt-3.5-turbo or similar

# 3. Reduce context size
# Limit issue description length
# Reduce system prompt length

# 4. Monitor LiteLLM logs
docker-compose logs litellm | grep -i "latency\|timeout"

Configuration Issues

Environment Variables Not Loading

Symptom: Configuration values not being used.

Solutions:

bash

# 1. Check .env file exists
ls -la goway/.env

# 2. Verify format (no spaces around =)
# GOOD:   DATABASE_URL=postgres://...
# BAD:    DATABASE_URL = postgres://...

# 3. Restart after changing .env
docker-compose restart goway

# 4. For docker-compose, use env_file
services:
  goway:
    env_file:
      - ./goway/.env

Seeding Fails

Symptom:

Failed to seed tasks/mappings

Solutions:

bash

# 1. Check YAML file syntax
cd goway/seeding
yamllint tasks.yaml

# 2. Verify database connection
psql $DATABASE_URL -c "SELECT 1;"

# 3. Check logs for specific error
docker-compose logs goway | grep -i "seed"

# 4. Try seeding manually
curl -X POST http://localhost:8000/api/tasks/seed -v

Getting More Help

If none of these solutions work:

Check Logs:
bash
```
docker-compose logs -f goway
```
Enable Debug Logging: Add to goway/.env:
bash
```
LOG_LEVEL=debug
```
Search GitHub Issues: Check if someone else has had the same problem: https://github.com/amansrivastava/hacky-automation/issues
Create an Issue: If you've found a bug, create a new issue with:
- Description of the problem
- Steps to reproduce
- Relevant logs
- Environment information (OS, Docker version, etc.)
Check Documentation:

Common Error Messages

Error	Likely Cause	Solution
`connection refused`	Service not running	Start the service
`authentication failed`	Wrong credentials	Check .env file
`port already allocated`	Port in use	Change port or kill process
`no such host`	Wrong hostname	Check service name in docker-compose
`context deadline exceeded`	Timeout	Increase timeout or check network
`permission denied`	File permissions	Check file ownership
`no space left`	Disk full	Clean up Docker resources

Troubleshooting ​

Database Issues ​

Connection Refused ​

Authentication Failed ​

Dirty Migration State ​

LLM Service Issues ​

Service Unavailable ​

Model Not Found ​

Rate Limiting / API Errors ​

Issue Tracker Issues ​

Updates Not Posting ​

Webhook Not Received ​

NATS Issues ​

Connection Failed ​

Frontend Issues ​

API Connection Failed ​

Build Failures ​

Docker Issues ​

Container Won't Start ​

Port Already in Use ​

Out of Disk Space ​

Performance Issues ​

Slow Startup ​

High Memory Usage ​

Agent Responses Slow ​

Configuration Issues ​

Environment Variables Not Loading ​

Seeding Fails ​

Getting More Help ​

Common Error Messages ​

Troubleshooting

Database Issues

Connection Refused

Authentication Failed

Dirty Migration State

LLM Service Issues

Service Unavailable

Model Not Found

Rate Limiting / API Errors

Issue Tracker Issues

Updates Not Posting

Webhook Not Received

NATS Issues

Connection Failed

Frontend Issues

API Connection Failed

Build Failures

Docker Issues

Container Won't Start

Port Already in Use

Out of Disk Space

Performance Issues

Slow Startup

High Memory Usage

Agent Responses Slow

Configuration Issues

Environment Variables Not Loading

Seeding Fails

Getting More Help

Common Error Messages