> ## 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 solutions for Bud AI Foundry Router

<Note>
  This guide covers common problems when creating, editing, saving, and using routers in Bud AI Foundry.
</Note>

## Router Creation Issues

### Project Selection Is Required

**Problem**: The router cannot be created from the global flow.

**Solution**: Select a project in the **Select Project** step before clicking **Create Draft**. Routers are project resources and the creation request includes project context headers.

### Router List Does Not Show the New Router

**Problem**: A router was created but does not appear in the list.

**Solutions**:

1. Clear the search field.
2. Refresh the list so it reloads routers ordered by newest first.
3. Confirm you are viewing the correct project or global router listing.

## Editor Issues

### Action Catalog Is Empty

**Problem**: The editor opens, but no router actions are available.

**Solutions**:

<AccordionGroup>
  <Accordion title="Refresh action metadata">
    Reload the page to fetch `/routers/actions` again. Action metadata is cached for a short period in the browser session.
  </Accordion>

  <Accordion title="Check router API availability">
    Verify the Bud API serving `/routers/actions` is reachable and returns categories plus action metadata.
  </Accordion>

  <Accordion title="Check permissions">
    Confirm your user has access to router actions and the selected project.
  </Accordion>
</AccordionGroup>

### Connection Not Allowed

**Problem**: The editor rejects an edge and shows a warning.

**Solution**: Use the supported lanes only:

```mermaid theme={null}
graph LR
    Trigger((Trigger)) --> Signal[Signal]
    Trigger --> Projection[Projection]
    Trigger --> Decision[Decision]
    Decision --> Algorithm[Algorithm]
    Decision --> Plugin[Plugin]
```

If you tried Trigger → Algorithm or Trigger → Plugin, add a Decision between them. If you tried Signal → Decision or Projection → Decision, connect those nodes from Trigger and reference them inside the Decision configuration.

### Save Fails With Validation Errors

**Problem**: Clicking **Save** shows a validation notification.

**Solutions**:

1. Open the action mentioned in the error.
2. Fill all required fields.
3. For list-style fields, make sure required arrays contain at least one item.
4. Check patterns, numeric ranges, and minimum or maximum lengths.
5. Save again.

## Data Source Issues

### Endpoints Are Missing From Dropdowns

**Problem**: Endpoint selection fields are empty.

**Solutions**:

* Confirm the project has deployments or endpoints available.
* Refresh the router detail page so endpoints are fetched again.
* Verify the endpoint API returns records without requiring a project filter for router actions.

### Cluster Values Look Different Than Expected

**Problem**: Cluster dropdown values use cluster UUIDs rather than UI row IDs.

**Solution**: This is expected. Router data sources use the cluster's `cluster_id` because deployment-compatible workflows require the Bud cluster UUID.

## API Usage Issues

### Router Request Returns Authentication Error

**Problem**: Calling `v1/chat/completions` fails with an authentication error.

**Solutions**:

```bash theme={null}
# Confirm the Authorization header is present
Authorization: Bearer {API_KEY_HERE}

# Confirm Content-Type is JSON
Content-Type: application/json
```

Generate a fresh API key if the current key has expired or was revoked.

### Router Name Does Not Resolve

**Problem**: The chat completions request cannot find the router.

**Solutions**:

1. Confirm the request `model` exactly matches the router name.
2. Confirm the router is saved and active.
3. Avoid renaming production routers without updating clients.

### Routing Results Are Unexpected

**Problem**: Requests reach a different endpoint or policy path than expected.

**Debugging Steps**:

1. Review Decision rules for priority and conditions.
2. Check endpoint weights or fallback order in Algorithm actions.
3. Confirm Signal and Projection actions produce the values your Decision expects.
4. Test with a minimal prompt and then add request complexity gradually.