Gabriel Radureau
1aef136436
Co-authored-by: Gabriel Radureau <arcodange@gmail.com> Co-committed-by: Gabriel Radureau <arcodange@gmail.com>
108 lines
3.0 KiB
Markdown
108 lines
3.0 KiB
Markdown
# 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)
|