Troubleshooting

Connection or Authentication Errors

1. Verify FRESHDESK_DOMAIN and FRESHDESK_API_KEY are correctly set in Settings
2. Confirm the subdomain matches your Freshdesk URL (e.g., company.freshdesk.com, without https://)
3. Confirm the API key is active in Freshdesk — regenerate it from Profile settings → API if it was rotated
4. Check outbound HTTPS access from the NodeKAT container to <subdomain>.freshdesk.com
5. Use the Test Connection action on the Connectors page, or review server logs for the specific error

Search Returns No Results

1. Verify the Freshdesk connector is enabled on the Connectors page in the Admin UI
2. Try the manual override: prefix your query with /freshdesk
3. Note that the default search is scoped to Open tickets (status:2) — ask for other statuses explicitly (e.g., “resolved tickets about the VPN”)
4. If you filtered by company, confirm the company name matches the value in the cf_portal_name_ak field exactly
5. If you used a custom field filter, verify the field name and value are correct (see custom-field querying in Agent Tools)

Custom Field Query Returns 0 Results

The agent automatically retries custom-field queries that return no results. If it still fails:

1. Check the schema reference the agent injects — it lists each custom field, its type, and its choices
2. For nested fields, use the subcategory value, not the parent
3. Match the exact spelling, capitalization, and spacing of field values (they are case-sensitive)
4. For unindexed fields (cf_resolution_summary, cf_category, cf_sub_category, cf_root_cause), the query must use custom_string instead of the field name

Extraction Not Running

1. Verify Freshdesk is enabled on the Connectors page in the Admin UI
2. Confirm FRESHDESK_DOMAIN and FRESHDESK_API_KEY are set
3. Check that RQ workers are running: docker-compose ps rq-worker-1
4. Check the RQ Dashboard at http://localhost:9181 for failed jobs
5. Trigger extraction manually on the Connectors page

Extraction Stops Early / Rate Limited

Freshdesk applies API rate limits. During paginated extraction, FluidRAG stops gracefully when Freshdesk returns a 429 response and respects the Retry-After header. If extraction stops early:

1. Check the logs for rate-limit warnings
2. Wait for the retry window and trigger extraction again
3. Reduce the extraction window with a start_date_override if you are backfilling a large history

Agent Not Responding to Freshdesk Queries

1. Verify the Freshdesk connector is enabled on the Connectors page in the Admin UI
2. Confirm both FRESHDESK_DOMAIN and FRESHDESK_API_KEY are set
3. Check the Freshdesk connection status on the Connectors page
4. Try the manual override: prefix your query with /freshdesk