> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/hybrid-hivel-agent/7.-troubleshooting-and-security-notes.md).

# 7. Troubleshooting & Security Notes

### Troubleshooting

**\`validate\` fails - source unreachable**

* Check the URL is correct and reachable from this machine
* Check firewall allows outbound HTTPS to the source
* For self-signed certs: add no\_verify\_ssl: true (Jira / GitLab) or skip\_ssl\_verification: true (GitHub / Bitbucket)

\`**validate\` fails - Hivel API unreachable**

* Check outbound HTTPS to api.hivel.ai is allowed
* Verify HIVEL\_API\_TOKEN is set and valid

**Issues missing from Jira sync**

* Check earliest\_issue\_date - issues before this date are excluded
* Test your issue\_jql\_filter in Jira's issue navigator first

**Custom Jira field not appearing**

* Run config fields to find the correct field ID
* Add to extra\_fields in config

**GitHub rate limiting**

* The agent proactively checks rate limits before each batch and sleeps until reset
* Reduce concurrent\_threads if you're seeing persistent throttling

**Azure DevOps Server (on-prem) - PRs outside the requested date window**

* Older API versions (7.0) don't honor server-side date filtering - the agent works around this automatically, but confirm api\_version matches your instance if PR counts look off
* Double-check is\_server: true and url point at the full collection URL (e.g. <https://host/tfs/CollectionName>), not just the host

**Debug HTTP traffic**

```
./hivel-agent --config config.yml --env-file .env sync --debug-requests
# output goes to debug.log in current directory
```

### Security notes

* **Only metadata is sent to Hivel.** No source code, file contents, attachments, or analytics data.
* **No hidden telemetry.** The agent sends nothing beyond the metadata payload described in this document.
* **Agent logs are opt-in.** Log streaming to Hivel is disabled by default (stream\_logs: false). Enable only when working with Hivel support.
* **Config upload is opt-in.** Disabled by default (send\_agent\_config: false). When enabled, all credential fields are replaced with **\*\*\*** before upload.
* **Credentials are never uploaded.** Tokens and passwords never leave your network.
* **S3 upload uses short-lived presigned URLs** issued by Hivel - the agent never holds S3 credentials.
* **All communication is over HTTPS/TLS.**
* No inbound connections for hivel-agent itself, it requires no open ports on the VM. The Claude OTel Collector is the one exception: if you enable it for Claude Code usage tracking, it requires inbound TCP **4317** (OTLP gRPC) and/or TCP **4318** (OTLP HTTP), see [Claude OTel Settings](/hybrid-hivel-agent/5.-configuration-reference/claudeotel-settings-claudeotel.md).

{% columns %}
{% column %} <a href="/hybrid-hivel-agent/6.-updating-the-agent-and-credentials.md" class="button primary" data-icon="backward">6. Updating the Agent and Credentials</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/hybrid-hivel-agent/8.-work-metrics-credentials-and-controls.md" class="button primary" data-icon="forward">Work-metrics</a>
{% endcolumn %}
{% endcolumns %}