Troubleshooting
Begin with the affected layer: browser, application API, pipeline, integration, segmentation or email. Keep the exact error and typed object identity before changing data.
Common symptoms
| Symptom | Checks |
|---|---|
| No territory or no visible work | User assignments, business groups, monitored changes, module filters and zoom |
| Counter larger than map/tree | Detailed display limit, viewport and overlapping groups/rules |
| Empty heatmap | Network/API result, filters and browser console; check the deployed CSP if a worker is blocked |
| Background absent | Layer URL/capabilities, HTTPS, permissions, projection and active composition |
| Review tracking unavailable | API error and schema version; do not force decisions in SQL |
| Approved object absent from reference | Integration root/blocker details and last confirmed execution |
| Prepared batch but failed service | Child executor stderr and outcome; preparation is not the final check |
| Reference current but sections old | Segmentation enabled state, source batch and latest run result |
| Missing notification email | Verified address, subscription eligibility, worker and SMTP monitoring |
| Permission error after upgrade | Effective service account, parent traversal and documented ACLs on replaced files |
Integration incident
Collect the batch ID, report, execution stderr and verification.json when present. Record the target database name and mode without disclosing credentials. Include affected identities as type/id/version, not an untyped number.
For needs_review, retain the existing batch and evidence. Inspect before recovery; do not repeat append blindly. A pending/refused dependency is a business decision issue; a context or verification mismatch requires technical analysis. Preserve historical context instead of replacing it with a live OSM download.
Service inspection
These commands read status; they do not run an append:
sudo systemctl status lbt-integration.service --no-pager
sudo systemctl cat lbt-integration.service
sudo journalctl -u lbt-integration.service --since '1 hour ago' --no-pager
sudo systemctl status lbt-segmentation.timer --no-pager
An inactive oneshot after successful completion is expected. Check timers separately. Inspect effective unit overrides before assuming the repository's schedule or paths are active.
Report a reproducible issue
Provide application version/commit, deployment type, exact action, expected and actual result, timestamp/time zone, relevant service result and sanitised diagnostics. For map problems add zoom, territory, filters and browser error; for data problems add type, ID and version.
Do not send env files, database passwords, SMTP secrets or email action tokens. If a screenshot contains a user's address or internal URL, redact it first.