# Troubleshooting

Common issues and their resolution. Extracted from the original `AGENTS.md` and merged with relevant sections from `AGENT_USAGE_GUIDE.md` and `BDD_GUIDE.md`. Refer back to those guides for context-specific troubleshooting (agent workflows, BDD test failures).

## Port Already in Use

```bash
# Find and kill process using port 8080
kill -TERM $(lsof -ti :8080)

# Force kill if graceful does not work
kill -9 $(lsof -ti :8080)
```

## Server Not Responding

```bash
# Check if running
curl -s http://localhost:8080/api/health

# Restart server using control script
./scripts/start-server.sh restart

# View recent logs
./scripts/start-server.sh logs
```

If health endpoint returns connection refused, the server may have crashed. Check logs in `./scripts/start-server.sh logs` for stack traces.

## Dependency Issues

```bash
# Clean and rebuild
go mod tidy
go build ./...

# If dependency version conflicts persist
go mod download
go mod verify
```

## Tests Failing

### Unit tests

```bash
# Run with verbose output
go test -v ./...

# Check specific test
go test ./pkg/greet/ -run TestName
```

### BDD tests

See [`BDD_GUIDE.md`](BDD_GUIDE.md) for the full BDD troubleshooting workflow (Godog setup, scenario isolation, step matching). Common BDD issues:

- **Step not found** → check `pkg/bdd/steps/` for the step definition file
- **Scenario state leaking** → review [ADR-0025](../adr/0025-bdd-scenario-isolation-strategies.md) for the isolation pattern
- **Database not reset** → ensure the test fixtures cleanup runs (BDD scenario After hooks)

## Configuration Not Loading

The application logs the configuration source at startup. Check logs for:

```
[INF] Configuration loaded from: file:config.yaml
# or
[INF] Configuration loaded from: env
# or
[INF] Configuration loaded from: defaults
```

If config is not loading as expected:

1. Verify file exists and is readable: `ls -la config.yaml`
2. Verify env vars are exported: `env | grep DLC_`
3. Check for typos in keys (case-sensitive)
4. Review [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md) section "Configuration troubleshooting"

## OpenTelemetry Not Tracing

1. Verify Jaeger is running: `docker ps | grep jaeger`
2. Check `DLC_TELEMETRY_ENABLED=true` in environment or `telemetry.enabled: true` in config
3. Verify OTLP endpoint reachable: `nc -zv localhost 4317`
4. Check sampler is not `always_off`
5. See [`OBSERVABILITY.md`](OBSERVABILITY.md) for full setup

## Build Failures

```bash
# Clear caches
go clean -cache -modcache
go mod download

# Rebuild
go build ./...
```

If errors persist, see [`local-ci-cd-testing.md`](local-ci-cd-testing.md) for the CI/CD pipeline that mirrors the production build.

## Where to Look Next

- **Agent-specific issues** (vibe, mistral, programmer agent) → [`AGENT_USAGE_GUIDE.md`](AGENT_USAGE_GUIDE.md)
- **BDD-specific issues** → [`BDD_GUIDE.md`](BDD_GUIDE.md)
- **Version/release issues** → [`version-management-guide.md`](version-management-guide.md)
- **CI/CD issues** → [`local-ci-cd-testing.md`](local-ci-cd-testing.md)