Skip to main content

​
Connector Does Not Appear in the Registry

Symptoms
  • Search returns no results.
  • The connector card is missing from the Connectors tab.
Fixes
  • Clear the search term and retry.
  • Confirm the registry service is reachable.
  • Use a custom MCP gateway if the connector is not available in the registry.

​
Credential Validation Fails

Symptoms
  • The add-connection drawer will not submit.
  • The backend returns a validation error.
Fixes
  • Complete every required credential field.
  • Confirm field names match the connector or provider schema.
  • For key-value arrays, verify both keys and values are populated.
  • Recheck API key, header, URL, or OAuth app values with the provider.

​
OAuth Redirect Does Not Return to the Agent

Symptoms
  • OAuth completes but Bud Admin opens the wrong page.
  • The connection still appears unauthorised.
Fixes
  • Retry from the agent builder so Bud can save the return context.
  • Confirm the provider redirect URI points to the Bud connector OAuth callback.
  • Check that the state value was not stripped by a proxy or browser extension.

​
Tools Do Not Load

Symptoms
  • The connection expands but shows no tools.
  • The fetch tools action fails.
Fixes
  • Complete OAuth first for OAuth connectors.
  • Confirm the gateway is enabled.
  • Verify the connection is global or shared with the agent’s project.
  • Fetch tools again after credential or provider permission changes.

​
Tools Attach but the Button Shows an Error

Bud treats any successful 2xx response as success unless the body explicitly contains success: false. If the tools appear after refresh, the backend operation likely succeeded and the UI status handling should be inspected.

​
Agent Cannot Use an Attached Tool

Fixes
  • Confirm the exact tool IDs are selected for that gateway.
  • Confirm the agent prompt configuration contains the gateway reference.
  • Verify the external provider account has permission to perform the tool action.
  • Detach and attach again after changing gateway credentials.

​
Event Connection Scope Is Rejected

Symptoms
  • Creating a global event connection returns a validation error.
  • Creating a project event connection returns a validation error.
Fixes
  • For global scope, do not send project_ids.
  • For project scope, send a non-empty, deduplicated project_ids list.
  • Ensure the current project ID is included for project-scoped trigger authoring.

​
Deleting vs Detaching Confusion

  • Detach removes a connection from one agent.
  • Delete removes the shared gateway or event connection.
Use detach for agent-specific cleanup. Use delete only when the shared connection should no longer exist.