Troubleshooting
Common setup errors, FTPR issues, rate limits, Docker token gotchas, and log commands.
| Symptom | Likely cause | Fix |
|---|---|---|
| Setup error | Missing credentials or squad mapping | Set provider credentials + teams |
/health 503 | Not ready_for_live | Fix config errors in logs |
| ClickUp API 404 on team | Wrong clickup.workspace | Use Team ID from ClickUp URL |
| FTPR always 100% (Jira) | Changelog not loaded | Config tab → changelog errors |
| FTPR n/a (ClickUp) | No fail tags / automations | Set fail_tags + backward-move automation |
| Cycle time empty | Wrong cycle_start_statuses | Match your board’s in-progress column |
| Custom field chart missing | Wrong field name | Copy exact name. check Config audit |
| Ambiguous Jira field | Duplicate display names | Rename in Jira admin or use unique name |
| Status warnings | Typo vs board | Copy exact status name |
| ClickUp API 429 / rate limit banner | Plan cap or burst traffic | Wait and refresh. set api.clickup_plan to match workspace tier |
| Slow ClickUp first load | Large workspace | Normal (2–5 min). narrow date range. cache helps on refresh |
| Empty bug backlog (ClickUp) | Bug rules don’t match open tasks | Check bugs.tags, title prefix, custom item types |
| Empty squad tab (ClickUp) | Tasks on shared folder, wrong squad | Set use_squad_field: true, match squad_value, confirm dropdown label in ClickUp |
| Wrong squad tab (ClickUp) | Shared list, ambiguous routing | Give each squad unique list_ids where possible, or use squad dropdown tiebreaker |
| Jira works after token edit but old token still used | docker compose restart without recreate | docker compose up -d --force-recreate after .env changes |
| Code fix not visible after upgrade | Old image still loaded | Load the new pulse-x.y.z-image.tar.gz, update the tag in docker-compose.yml, docker compose up -d |
| Large Unknown on Bugs by priority | urgency_field set but many bugs lack the dropdown | Fill the field on bugs, or clear urgency_field to use native priority only |
| Chart count ≠ drill-down modal | Stale browser cache after upgrade | Hard refresh (Cmd+Shift+R). counts use priority_label only |
Logs: docker compose logs -f pulse