Troubleshooting
Troubleshooting
| Field | Value |
|---|---|
| Distribution | BSS — OpenSOF |
| Product | OpenSOF |
| Release | 0.15.1 |
| Deployment | opensof.bss.dev |
| Source | /srv/bss/releases/OpenSOF-v0.15.0-20app |
| Evidence | Operational diagnostic standard |
| Source fingerprint | cda583b42f2a0d296b268ab5b174932a378c8be6fb52ffa1af14af896e990f6e |
| Status | Generated baseline — human review required |
Verification boundary: This page combines platform design guidance with static evidence from the release. It does not prove that every detected interface is enabled, reachable, secure, or operational in the deployed environment.
Diagnostic sequence
- State the exact user-visible symptom, start time, scope and last known good state.
- Check DNS/routing/time before assuming an application defect.
- Check process/container state and recent logs.
- Test the backend locally on its bound address/port.
- Test proxy/TLS path and WebSocket upgrade separately.
- Test dependencies: database, OpenBus, OpenKnowledge, OpenFiles and external services.
- Reproduce one primary workflow with correlation identifiers and capture evidence.
- Apply the smallest reversible change, then retest all layers.
Symptom matrix
| Symptom | Likely layer | First checks |
|---|---|---|
| Connection refused | Process/socket | systemctl status, ss -lntup, local curl |
| Empty response/reset | App/upstream crash or protocol mismatch | Application logs, internal HTTP response, proxy protocol. |
| 502/504 | Reverse proxy/upstream | nginx -t, error log, proxy_pass, backend latency |
| Page loads but live data fails | WebSocket/CORS/auth | Browser network console, upgrade headers, token/role, route base. |
| Wrong distribution/branding | Nginx/service instance | Hostname routing, service unit, current release symlink, environment. |
| Tracks/tasks/products missing | Dependency/data flow | Producer logs, OpenBus/API, authorization, semantic type, time window. |
| Intermittent correlation error | Time/PNT/data quality | Clock offset, source timestamps, coordinate frame and calibration. |
Evidence rule
Before changing configuration, preserve the relevant logs, status output, request/response, release version and timestamps. Troubleshooting without evidence tends to become configuration roulette—with worse odds and fewer free drinks.
Maintainer Notes
Add human-reviewed deployment notes, corrections, decisions, screenshots, and links here. Content outside the generated block is preserved on future runs.