How to Troubleshoot Common Protocol Issues

This guide provides practical steps to diagnose and resolve frequent SAS-CBSD protocol problems based on WINNF-TS-0016.

Overview

Common issues fall into categories: connectivity/TLS, registration/grant failures, heartbeat problems, and measurement/grouping quirks. Early logging and structured diagnostics save time.

Key Bridge SAS Tip: Enable verbose logging of all requests/responses (including headers and timestamps). Our support team can analyze logs quickly to pinpoint issues.

Common Issue Categories & Solutions

1. Connectivity & TLS Problems

Symptom	Likely Cause	Diagnostic Steps & Fix
No response / timeout	Firewall, wrong URL, TLS failure	Ping SAS domain; test with health endpoint GET
401/403 Unauthorized	Invalid client certificate	Verify cert contains correct FCC ID/serial; test health endpoint
Handshake failure	Outdated TLS version or cipher	Ensure TLS 1.2+; match supported ciphers

Quick Test: Use the health endpoint (GET only):

curl -v --cert cert.pem --key key.pem --cacert root.pem https://sas.cbrs.keybridgewireless.com/cbsd/api/v1.2/health

2. Registration Failures

Code/Symptom	Cause	Fix
101 BLACKLISTED	FCC ID/serial blocked	Contact support; verify CPI installation
103 MISSING_PARAM	Missing installationParam or userId	Add required fields (esp. for Cat B: height, antenna)
104 INVALID_VALUE	Latitude/longitude out of range	Ensure valid US coordinates; heightType AGL/AMSL

Tip: For indoor Category B, ensure professional installer attestation is accurate.

3. Spectrum Inquiry / Grant Denials

Symptom	Cause	Fix
No available channels / 400 GRANT_FAILURE	Location in DPA, high interference	Send received power measurements; lower maxEirp
Partial/narrow grant	Aggregate interference limits	Enable grouping (e.g., INTERFERENCE_COORDINATION) + measurements
Repeated denials	No measurements sent	Declare measCapability and include rcvdPower reports

Pro Tip: Requesting the full CBRS band with measurements often yields better results than narrow requests.

4. Heartbeat & Runtime Issues

Symptom	Cause	Fix
500 SUSPENDED_GRANT	Temporary DPA activation	Stop TX immediately; continue heartbeats
501 TERMINATED_GRANT	Permanent change (e.g., ESC detection)	Relinquish; request new grant on different channel
Heartbeat timeout	Network latency	Implement jitter; send early; exponential backoff

Tip: Log transmitExpireTime and heartbeatInterval — stop TX the moment expire time passes.

5. Measurement & Grouping Issues

Symptom	Cause	Fix
Lower EIRP than expected	No measurements or grouping	Enable both; use consistent groupId across devices
Group benefits not seen	Inconsistent groupingParam	Verify identical groupType/groupId on all CBSDs

Diagnostic Checklist

Logs: Capture full request/response JSON, TLS errors, timestamps.
Health Check: Confirm cert works via GET to health endpoint.
Measurements: Always include when capable — optional but highly beneficial.
Location Accuracy: Double-check GPS coordinates and height.
Firmware Version: Ensure compliant with latest WINNF-TS-0016/3002.
Contact Support: Share logs + CBSD serial/FCC ID for fastest resolution.

Best Practices for Prevention

Implement auto-retry with backoff for transient errors
Persist cbsdId and grantId across reboots
Monitor response codes and alert on patterns (e.g., frequent 400s)
Test new firmware in lab with health endpoint + sandbox SAS
Combine measurements + grouping for optimal performance

Next Steps

Review your logs against this guide
Reach out to Key Bridge support with specific error patterns