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

> Common issues and fixes for Agents in Bud AI Foundry

## Quick Diagnosis Flow

```mermaid theme={null}
graph TD
    A[Issue Observed] --> B{Where?}
    B -->|Creation| C[Validate workflow and project context]
    B -->|Execution| D[Check prompt config and target model]
    B -->|Tools| E[Verify connector auth and availability]
    B -->|Versioning| F[Validate selected/default version]
```

## Creation Issues

### Cannot create a new agent

**Likely causes**:

* Missing project context
* Insufficient permissions

**Fixes**:

* Re-open from the project Agents tab.
* Confirm manage-level project permissions.

### Drawer opens with stale data

**Likely cause**: Previous workflow/session state persisted.

**Fixes**:

* Start a fresh creation flow from **+ Create New**.
* Re-open the drawer after navigation reset.

## Execution Issues

### Agent output is inconsistent

**Likely causes**:

* Prompt not specific enough
* Missing structured schema constraints

**Fixes**:

* Strengthen system prompt instructions.
* Enable structured input/output and define variable types.

### Wrong model/deployment behavior

**Likely cause**: Incorrect target selected in configuration.

**Fixes**:

* Confirm selected deployment/model in agent settings.
* Re-run validation before saving.

## Tools and Connector Issues

### Connector does not appear as connected

**Likely causes**:

* Authorization incomplete
* Session not restored after OAuth callback

**Fixes**:

* Re-run connector authorization.
* Return to the same agent session and verify connector details panel.

### Tool calls fail at runtime

**Likely causes**:

* Insufficient connector permissions
* Downstream system unavailability

**Fixes**:

* Re-check connector scopes.
* Verify endpoint/service health on the external system.

## Versioning Issues

### New version not visible

**Fixes**:

* Refresh the Versions tab.
* Confirm save completed successfully.

### Default version not updating

**Fixes**:

* Retry set-default action.
* Confirm project-level permission to modify versions.