BranchPy
Log in

Docs-Builder

# Telemetry Troubleshooting

Version: 1.1.1
Last Updated: January 23, 2026

Common Issues

  • No telemetry file created: Mode is off or command not run from BranchPyApp; run branchpy telemetry mode --show and retry export.
  • Upload blocked (auth): Missing API key/token; set telemetry.auth_token or provide API key header for rc-backend. Use --dry-run to verify package before retrying.
  • Schema validation failed: Package contains raw paths/content; ensure plugins/extensions are updated and rerun export. Validation prevents upload until sanitized.
  • Size exceeds cap: Reduce time range (--from 1h) or bump telemetry.max_upload_size_mb. Large caches can be sampled via BRANCHPY_TELEMETRY_CACHE_SAMPLING_RATE.
  • Unicode errors: v1.1.1 is Unicode-hardened; if errors persist, confirm environment encoding is UTF-8 and rerun after clearing .branchpy/telemetry/*.jsonl.
  • Extension not logging: Ensure branchpy.telemetry.enabled is true and privacy level not minimal for detailed events. Check globalStorage path exists and not locked by AV.
  • Auto mode silent: Auto uploads only in auto mode; confirm interval and check last-upload status in Control Center.

Verification Steps

  • Run branchpy telemetry preview --json to inspect sanitized payload.
  • Open rc-metrics.json to verify no paths or content before upload.
  • Hit GET /api/telemetry/health to confirm backend is reachable.
  • Query GET /api/telemetry/stats after upload to confirm ingestion.

Support Artifacts

  • Logs: .branchpy/logs/telemetry*.log (if enabled), VS Code Control Center notification history.
  • Schema: BranchPyApp/branchpy/telemetry/package_schema.py (source of validation).