Troubleshooting

This page covers common issues encountered when using Progrid AI Lead Research and how to resolve them. Issues are organized by category for quick reference.

API and provider errors

“API key not configured” error

Symptom: Research job fails immediately with an error indicating the API key is missing.

Cause: The required API key has not been entered in the settings.

Solution:

1. Navigate to CRM ‣ AI Research ‣ Configuration ‣ Settings.

2. Verify that API keys are entered for:

   • Groq API Key (required for all jobs)

   • Brave API Key (required if using Brave or Mixed search)

   • Tavily API Key (required if using Tavily or Mixed search)

3. Click Save after entering or updating keys.

4. Re-run the research job.

See also

Provider setup

“401 Unauthorized” or “403 Forbidden” from provider

Symptom: Job fails during the search or normalize/score phase with an authentication error.

Cause: The API key is invalid, expired, or does not have the required permissions.

Solution:

1. Navigate to CRM ‣ AI Research ‣ Configuration ‣ Provider Status.

2. Click Test Connection for the failing provider.

3. If the test fails:

   • Log into the provider’s console (Groq, Brave, or Tavily).

   • Verify the API key is still active and has not been revoked.

   • Generate a new API key if needed.

   • Update the key in CRM ‣ AI Research ‣ Configuration ‣ Settings.

“429 Too Many Requests” or rate limit errors

Symptom: Job fails or slows down significantly with rate limit error messages in the log.

Cause: The module is making API calls faster than the provider allows.

Solution:

1. Navigate to CRM ‣ AI Research ‣ Configuration ‣ Settings.

2. Reduce the rate limit values:

   • Lower Groq Requests Per Minute (try 15-20 instead of 30)

   • Lower Brave Requests Per Second or Tavily Requests Per Second to 1

3. Click Save.

4. Wait a few minutes for any rate limit cooldowns to expire, then re-run the job.

Tip

If you frequently hit rate limits, consider upgrading to a paid plan with the provider, or reducing the Max Results value in your research jobs to decrease the total number of API calls needed.

“Connection timeout” or network errors

Symptom: Job fails with timeout or connection errors when trying to reach a provider API.

Cause: Network issues between your Progrid server and the provider’s API endpoint.

Solution:

1. Verify your server has internet access.

2. Check if the provider’s status page reports any outages:

   • Groq: status.groq.com

   • Brave: Check their status page or social media

   • Tavily: Check their status page or documentation

3. If using a proxy or firewall, ensure the following domains are allowed:

   • api.groq.com

   • api.search.brave.com

   • api.tavily.com

4. Increase the Fetch Timeout setting if pages are loading slowly.

Low confidence results

Results consistently below 50% confidence

Symptom: Most results have low confidence scores, and few or no CRM leads are being created automatically.

Cause: The target description is too vague, the search results are not relevant, or the web pages lack structured contact information.

Solutions:

• Be more specific in the target description. Instead of “businesses in Texas”, try “plumbing contractors in Austin TX with a website”. The more specific the input, the better the search queries and the more relevant the results.

• Add location and industry fields. Filling in the Location and Industry fields in the wizard helps generate more targeted search queries.

• Try a different search provider. Brave and Tavily return different results. If one provider yields low-quality results for your target, switch to the other or use Mixed mode.

• Reduce max results. A smaller number of highly relevant results is often better than a large number of marginally relevant ones. Try setting Max Results to 5 instead of 10.

Most results marked as “Unclear” activity status

Symptom: The majority of results have an unclear activity status rather than active or inactive.

Cause: The target websites do not contain enough information for the AI to confidently determine activity level. This is common for:

• Simple one-page websites with no blog or news section

• Websites that do not display copyright dates

• Businesses that do not maintain an active web presence

Solutions:

• This is expected behavior for some business types. Not all websites provide enough signals for confident activity assessment.

• Consider treating unclear results as potential leads that require manual verification.

• Focus on industries where businesses typically maintain active websites (technology, marketing, professional services).

No results found

Job completes with zero results

Symptom: The research job completes successfully but produces no results.

Causes and solutions:

1. Overly narrow search terms. Broaden the Target Description. Remove very specific qualifiers and try again.

2. Location too specific. If targeting a small geographic area, try broadening to the state or region level.

3. Search provider limitations. Some search providers return fewer results for certain query types. Try switching providers or using Mixed mode.

4. All results were duplicates. If the same businesses were found in a previous job, the deduplication logic may have filtered them out. Check the job’s log messages for deduplication activity.

Job stuck in “Searching” status

Symptom: The job status shows Searching but does not progress to Fetching.

Cause: The search provider API call may have timed out or returned an error that was not properly handled.

Solution:

1. Check the job’s chatter log for error messages.

2. Navigate to CRM ‣ AI Research ‣ Configuration ‣ Provider Status and test the search provider connection.

3. If the provider is working, try canceling the stuck job and creating a new one.

Cache issues

Stale data in results

Symptom: Research results contain outdated information that you know has changed on the target website.

Cause: The content cache is serving a previously downloaded version of the page.

Solution:

1. Navigate to CRM ‣ AI Research ‣ Configuration ‣ Cache Management.

2. Search for the specific URL in the cache.

3. Delete the stale cache entry.

4. Re-run the research job. The module will fetch a fresh copy of the page.

Alternatively, reduce the Cache Duration (Days) setting to force more frequent re-fetches.

Cache consuming too much storage

Symptom: The database is growing due to accumulated cache entries.

Cause: Over time, the Progrid.fetch.cache table accumulates entries from all research jobs.

Solution:

1. Navigate to CRM ‣ AI Research ‣ Configuration ‣ Cache Management.

2. Click Clear Expired Entries to remove entries older than the configured cache duration.

3. If storage is still a concern, click Clear All Cache and adjust the cache duration to a shorter period (e.g., 3 days instead of 7).

Queue and processing issues

Job stuck in “Queued” status

Symptom: The job remains in Queued status and never starts processing.

Cause: The background job processor (cron job) may not be running.

Solution:

1. Navigate to Settings ‣ Technical ‣ Automation ‣ Scheduled Actions.

2. Look for the AI Research scheduled action.

3. Verify it is active and check the Next Execution Date.

4. If the scheduled action is not running, click Run Manually to trigger it.

Note

Queue jobs require the Progrid server’s cron worker to be running. If you are using a development setup, ensure the server was started with the --workers flag or that the cron is being triggered manually.

Job fails repeatedly on the same phase

Symptom: Every time you run a job, it fails at the same pipeline phase (e.g., always fails at Normalizing).

Cause: There may be a systematic issue with the provider configuration or the data being processed.

Solutions:

1. Check the detailed error in the job’s chatter log.

2. If failing at Normalizing or Scoring, verify the Groq API key and test the connection.

3. If failing at Fetching, some target websites may be blocking automated access. Try different search terms that lead to different websites.

4. If failing at Delivering, check that the CRM module is properly configured with sales teams and salespeople.

Permission errors

“Access Denied” when creating a research job

Symptom: Clicking Create on the Research Jobs page produces an access error.

Cause: Your user account does not have the AI Research User or Manager group assigned.

Solution:

Ask your system administrator to assign the AI Research User group to your account. See Security for instructions on assigning groups.

Cannot access Configuration menu

Symptom: The CRM ‣ AI Research ‣ Configuration menu is not visible.

Cause: You have the AI Research User group but not the Manager group. Configuration is restricted to managers.

Solution:

Ask your system administrator to upgrade your access to the AI Research Manager group if you need to modify settings.