Skip to main content

🔌 Integration Troubleshooting

Below are solutions to common issues when integrating Beak AI with external systems, databases, and APIs.

Cannot connect to a database​

  • Verify database host, port, username, and password in your environment variables.
  • Ensure the database is accessible from the Beak AI deployment network.
  • Check firewall rules and security groups.
  • Confirm the correct database driver is installed and configured.

API integration fails (timeouts, 401/403 errors)​

  • Check the API endpoint URL and credentials (API keys, OAuth tokens).
  • Ensure the API is reachable from your Beak AI environment.
  • Review rate limits and quotas for the external API.
  • Inspect API documentation for required headers or parameters.
  • For Microsoft APIs, ensure the necessary API permissions are granted in your Azure app.
  • Make sure the credential includes the correct scope based on the API being used.
  • If the agent fails due to a missing access token, remove token-related info from the OpenAPI spec.

Timeout error during API skill execution​

  • If the agent is calling multiple APIs and the execution is taking too long, consider using Python code execution, which will be faster.

Data source not appearing in Studio​

  • Refresh the Studio UI and check logs for errors.
  • Confirm the data source is registered and enabled in the configuration.
  • Check for schema or permission issues on the external system.
  • Make sure the data source type filter matches the type you created (Database, System, File or Website).

Identifying which datasource was used by my agent​

  • Check the trace in AI Observability for your question.
  • Review which datasource was selected and the output returned from that datasource.

My credentials are constantly getting changed​

  • Credentials are not being changed or lost — they’re shown in encrypted form for security.
  • They will continue to work as expected.
  • You can update them with new values at any time.

Newly created credentials not appearing in skill credential mapping​

  • Add the skill to your agent first.
  • Then open the agent configuration and map the credential there.

Can't find the right credential type for my API skill​

  • Use the Custom Credential type, which lets you define the authentication header key and value.
  • If the API requires a more complex authentication mechanism, contact the Beak team to add the needed credential type.
  • Review the API’s documentation to understand what authentication method and credential format it requires.

Agent not able to fetch logs from Log Analytics workspace​

  • Ensure credentials are configured correctly with required access.
  • Use AI Observability to verify if the KQL query was generated as expected.
  • If the query is incorrect, review your table schema and additional info to guide proper KQL generation.

Webhook or event integration not triggering​

  • Verify the webhook URL is correct and publicly accessible if required.
  • Check for authentication or signature requirements.
  • Inspect logs for incoming requests and error responses.

Bad Request in API skill​

  • Verify your OpenAPI spec and the API URL in the skill configuration.
  • In AI Observability → Traces, check the final URL and request body to ensure they are correct.
  • Only configure endpoints that actually exist in the external API.

Tags in a prompt​

  • Tags are optional fields used to categorize and filter prompts.
  • They help organize and manage prompts more efficiently within the Studio.

Prompt not getting saved​

  • Try changing the name of the prompt — another prompt may already exist with the same name.
  • Ensure the prompt name does not contain unsupported or special characters.

SSL/TLS or certificate errors​

  • Ensure valid certificates are installed on both Beak AI and the external system.
  • For self-signed certificates, add them to the trusted store or disable verification (not recommended for production).

For persistent integration issues, consult the Integration Guide or contact Beak AI support.