Troubleshooting¶

Common Failure Patterns¶

Symptom	Likely Cause	Fix
`op` command missing	1Password CLI not installed	install `op`
token validation failure in `mise run 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
mise run up --mode=plan
mise run reset