Troubleshooting¶

Common Failure Patterns¶

Symptom	Likely Cause	Fix
`op` command missing	1Password CLI not installed	install `op`
token validation failure in `./init`	expired `GITLAB_PASSWORD`	rotate token in GitLab + 1Password
services fail to connect to DB/MQ	vendor services not healthy	check `docker compose ps`, restart stack
port bind errors	host port collision	override ports in `.env`

Diagnostic Flow¶

flowchart TD
  Fail[Stack issue] --> Logs[Check docker compose logs]
  Logs --> Health[Check health statuses]
  Health --> Env[Validate environment files]
  Env --> Ports[Check host port collisions]
  Ports --> Reset[Reset and restart stack]

High-Signal Commands¶

docker compose ps
docker compose logs --tail=200 bf-manage-core
./up --mode=plan
./reset