Troubleshooting Common Issues

11.1 Universal first step

When troubleshooting, first collect the run ID, coordinator version, client versions, task configuration, participant list, certificates in use, secure aggregation setting, DP setting, recent deployment changes, and relevant logs. The reference repository provides a diagnostic script that gathers non-sensitive operational information for triage.

./scripts/diagnose.sh --run-id $RUN_ID --env $ENVIRONMENT --since 2h

11.2 Troubleshooting table

Issue	Likely cause	First checks
Server not reachable	Coordinator health, DNS, security group, routing, or service crash.	Check health endpoint, DNS resolution, service logs, and recent deployments.
Client cannot connect	Network path, endpoint allow-list, DNS, or mTLS certificate problem.	Check endpoint, outbound firewall, certificate validity, and coordinator logs.
TLS handshake fails	Client certificate is missing, expired, revoked, or not issued by expected CA.	Verify certificate chain, common name or identity, expiry, and revocation list.
Round aborts	Not enough clients completed the round, especially when secure aggregation quorum is required.	Check client health, timeout settings, cohort size, and dropout logs.
Audit log delivery lagging	Log shipping or central audit account pipeline failure.	Check log delivery status, permissions, storage capacity, and alarm history.
Poor model performance	Data heterogeneity, schema mismatch, small local datasets, label imbalance, or overly strong DP noise.	Compare local baselines, per-client metrics, data profiles, and DP settings.
Privacy budget exceeded	Too many rounds, too high sampling rate, or DP configuration not aligned with planned run.	Recompute budget, reduce rounds, adjust batch size, or revisit DP settings.
Unexpected participant behaviour	Misconfiguration, stale client image, low-quality data, or free-rider-like contribution.	Check client version, data manifest, contribution metrics, and participant agreement.