Why Is My Workflow Failing with an AI Provider Error in Dave by voolama?

Summary

The steps

1. 1

   Read the error message on the failed instance

   Every workflow instance failure in Dave by voolama (hellodave.ai) leaves an error message in the tasks table on the instance detail page. The error message names the cause. Reading it before touching the provider saves time and prevents incorrect fixes. Sourced from the admin-providers help documentation, DEV v0.11.0, confirmed against content_orchestrator main at commit ddb945f, 2026-08-30.

   Navigate to Instances in the sidebar. Filter by failed status. Click the most recently failed instance. On the instance detail page, find the tasks table. Locate the row with a failed status (red badge). Click the Type link to open the task detail and read the error message. See How Do I Read a Workflow Instance's Output in Dave by voolama? for the full instance detail page walkthrough.

   Do this

   • Navigate to Instances in the sidebar.
   • Use the status filter to select failed.
   • Click the most recently failed instance.
   • On the instance detail page, find the tasks table. Locate the row with a failed (red) status badge.
   • Click the Type link to open the task detail. Read the error message. Note the exact wording: it maps to one of the four failure modes in the next step.
   • Also watch the run timeline: see Watch a Run and Read Its Timeline. The timeline shows which node failed and at what point in the execution.

   Example

   An Admin opens a failed instance. The tasks table shows one row with a red failed badge. The Type link reads 'agent_interaction'. The task detail shows the error: 'Request failed: 401 Unauthorized - invalid API key.' The Admin recognises this as failure mode 1 (expired or revoked key) and proceeds to step 2 without touching the provider yet.

   Best practice

   Do not edit the provider until you have read the error message and identified the failure mode. Changing the wrong field can mask the real cause. The admin-providers help documentation documents four distinct failure modes, each with a different fix. Matching the error string to the correct mode before acting is the only reliable diagnostic path.

2. 2

   Match the error to one of the four failure modes

   Four provider failure modes are documented in the admin-providers help documentation, DEV v0.11.0, confirmed 2026-08-30. Each has a specific error pattern and a specific fix. Match the error message from step 1 to the correct failure mode before touching the provider.

   Error pattern	Failure mode	Fix
   'authentication', 'invalid API key', '401 Unauthorized'	Expired, revoked, or incorrect API key	Edit the provider, enter a valid key, click Fetch Models, then Update Provider.
   'Failed to fetch models', 'connection refused', 'failed to reach', base URI in the error	Wrong base URI or service unreachable	Edit the provider, verify the base URI, click Fetch Models. For Azure OpenAI, confirm the deployment-specific endpoint.
   'rate limit', '429 Too Many Requests', 'quota exceeded'	AI service usage quota exceeded	Check the provider platform usage dashboard. Upgrade plan, reduce volume, or spread load across multiple providers. No key rotation needed.
   Agent fails immediately after a provider was deleted, or 'provider not found'	Provider deleted while agents still reference it	Recreate the provider at Admin, then API Management, then Providers. Verify with Fetch Models before saving.

   The admin-providers help documentation states for the rate limit case: "Check your usage dashboard on the provider's platform (e.g., OpenAI Usage, Anthropic Console). Upgrade your plan, reduce request volume, or spread load across multiple providers." Rate limit errors do not require a key rotation: the key is valid, the quota is exhausted.

   OWASP Top Ten 2021 A02 (Cryptographic Failures, criterion 2) applies to failure mode 1: an expired or revoked key left in the encrypted store is a stale credential. Rotating the key promptly closes the A02 exposure window. OWASP Top Ten 2021 A05 (Security Misconfiguration, criterion 5) applies to failure mode 2: a wrong base URI is a misconfiguration that prevents the provider from functioning and should be corrected promptly per A05's remediation guidance.

   Do this

   • Read the error message from step 1.
   • Match it to one of the four rows in the table above.
   • Proceed to step 3 for failure modes 1 and 2 (key or base URI problems).
   • For failure mode 3 (rate limit): check the AI service usage dashboard directly. No provider edit is needed.
   • For failure mode 4 (deleted provider): proceed to step 3 to recreate the provider.

   Example

   The Admin's error message is '429 Too Many Requests - rate limit exceeded'. This matches failure mode 3. The Admin does not edit the provider. Instead, they open the OpenAI Usage dashboard at platform.openai.com/usage and confirm the account has hit its monthly token limit. They upgrade the OpenAI plan and relaunch the instance. No key rotation was required.

   Best practice

   The admin-providers help documentation recommends: "Spread load across multiple providers." If rate limit errors are recurring, create a second provider for the same AI service using a different API key. Agents can then be distributed across the two providers. Verify: after creating the second provider, click Fetch Models to confirm it can reach the service before assigning any agents to it.

3. 3

   Fix the provider at Admin, API Management, Providers

   For failure modes 1 (bad key), 2 (wrong base URI), and 4 (deleted provider), the fix is in the provider record at Admin, then API Management, then Providers. Only the Admin role can access this page. Sourced from the admin-providers help documentation, DEV v0.11.0, confirmed 2026-08-30.

   Failure mode 1 (bad key): click the pencil icon on the provider card. Enter the new API key in the API Key field (masked by default; click the eye icon to reveal). Click Fetch Models before clicking Update Provider. A successful fetch confirms the new key is valid at the network level. The admin-providers help documentation states: "Click Fetch Models to confirm the new key works before saving."

   Failure mode 2 (wrong base URI): click the pencil icon. Check the Base URI field against the service documented endpoint. For Azure OpenAI, the base URI is deployment-specific. The admin-providers help documentation states: "If using Azure OpenAI or a custom endpoint, confirm the URL is correct and the service is online." Click Fetch Models after correcting the URI. Per OWASP Top Ten 2021 A05 (Security Misconfiguration, criterion 5), a wrong base URI is a misconfiguration: correcting it and verifying with Fetch Models is the A05 remediation step.

   Failure mode 4 (deleted provider): click Add Provider. Fill in the Name, Provider Type, Base URI, and API Key. Click Fetch Models to verify. Click Create Provider. Then update any agents that referenced the old provider to point to the new one.

   Do this

   • Navigate to Admin, then API Management, then Providers.
   • For failure modes 1 and 2: click the pencil icon on the affected provider card.
   • For failure mode 1: enter the new API key. For failure mode 2: correct the Base URI.
   • Click Fetch Models. Confirm the model list populates. If it fails, re-read the error and correct the key or URI before proceeding.
   • Click Update Provider.
   • For failure mode 4: click Add Provider, fill in all fields, click Fetch Models to verify, then click Create Provider. See Add an AI Provider for the full creation walkthrough.

   Example

   The Admin clicks the pencil icon on 'OpenAI Production'. The edit form opens. The Admin clears the API Key field and pastes the new key from the OpenAI dashboard. They click Fetch Models. The model list populates with 6 models. The Admin confirms the 4 models they had before are present and selects them. They click Update Provider. The provider card updates. The fix is complete before any instance is relaunched.

   Best practice

   The admin-providers help documentation states: "Keep at least one active provider: If all providers are deleted or misconfigured, no agent can execute AI calls and all workflows that rely on agents will fail." Before fixing a provider, confirm at least one other provider is correctly configured. If the failing provider is the only one, fix it before relaunching any instances. Verify: after saving, click the chevron on the provider card to expand it and confirm the model list is non-empty.

4. 4

   Verify the fix and relaunch the failed instance

   After fixing the provider, verify the fix before relaunching the failed instance. The admin-providers help documentation states: "After creating or editing a provider, use Fetch Models to verify that the API key and base URI are correct. A successful fetch confirms the provider can reach the AI service." Sourced from the admin-providers help documentation, DEV v0.11.0, confirmed 2026-08-30.

   Fetch Models confirms the provider can reach the AI service. A completed test instance confirms the agent can execute end-to-end. Both verifications are independently observable without trusting the vendor.

   Do this

   • Confirm Fetch Models succeeded in step 3 (model list is non-empty on the provider card).
   • Launch a test instance: see Launch an Instance.
   • Watch the run: see Watch a Run and Read Its Timeline. A completed run confirms the provider fix is working end-to-end.
   • If the test instance also fails: return to step 1 and re-read the error message. The failure mode may have changed (for example, the key was correct but the service is now rate-limiting).
   • Once the test instance completes, relaunch the original failed instance.

   Example

   After updating the provider key, the Admin launches a test instance of the 'Content Draft' workflow. The run completes in 14 seconds. The Admin opens the instance detail page and confirms the Agent Interaction node completed with a non-empty output. They then navigate to Instances, find the original failed instance, and relaunch it. It completes successfully. The provider failure is resolved.

   Best practice

   The admin-providers help documentation states: "Curate your model catalog: Only include models your team actually uses. A smaller catalog makes model selection in agent configuration faster and less error-prone." After a provider fix, review the model catalog and remove any models that are no longer in use. Verify: click the chevron on the provider card and confirm only the models your agents reference are listed.

Which provider types does Dave by voolama support?

What this guide does not cover