> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budecosystem.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve common connector, OAuth, tool, scope, and trigger issues

## 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.

```mermaid theme={null}
flowchart TD
  A[Connection issue] --> B{Type}
  B -->|MCP gateway| C[Check credentials, enabled state, scope, OAuth]
  B -->|Tool attach| D[Check prompt ID, selected tool IDs, permanent flag]
  B -->|Event connection| E[Check descriptor fields, scope payload, webhook]
  C --> F[Retry operation]
  D --> F
  E --> F
```

## 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.