Skip to content

Add Common Issues troubleshooting table to databricks-agent-bricks skill #252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
CheeYuTan wants to merge 1 commit into from
Closed

Add Common Issues troubleshooting table to databricks-agent-bricks skill #252

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions databricks-skills/databricks-agent-bricks/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,6 +195,21 @@ manage_mas(
)
```

## Common Issues

| Issue | Solution |
|-------|----------|
| **KA creation fails with "endpoint not found"** | The vector search endpoint must exist before creating a KA. Create it first with `manage_vector_search(action="create_endpoint")` |
| **KA not indexing documents** | Check that the source volume path is correct and contains supported file types (PDF, TXT, HTML, DOCX, MD). Verify the KA's data source configuration |
| **KA returns "I don't know" for relevant questions** | The chunking or embedding may not capture the answer. Try adjusting chunk size, adding more documents, or rephrasing the question to match document terminology |
| **Genie Space returns wrong SQL** | Add sample questions with verified SQL in the space instructions. Use `curate_genie_space` to add golden SQL examples that guide the model |
| **Genie Space "no tables found"** | Ensure tables are in the configured catalog/schema and the service principal has `SELECT` permission. Tables must have column comments for best results |
| **MAS supervisor routes to wrong agent** | Improve the `instructions` field with explicit routing rules. Use numbered conditions and be specific about which query patterns map to which agent |
| **MAS agent timeout** | Individual agent calls have a default timeout. For long-running agents, increase the timeout in the supervisor configuration or break the task into smaller steps |
| **"PROVISIONING" state stuck** | Agent bricks endpoints can take 5-15 minutes to provision. Poll status with `get` action. If stuck beyond 20 minutes, delete and recreate |
| **KA response includes irrelevant chunks** | Enable reranking if available, or reduce the number of retrieved chunks. Add negative examples to the instructions to guide filtering |
| **Permission denied creating agent bricks** | Requires workspace admin or `CREATE_SERVING_ENDPOINT` permission. The service principal also needs access to underlying data sources |

## Related Skills

- **[databricks-genie](../databricks-genie/SKILL.md)** - Comprehensive Genie Space creation, curation, and Conversation API guidance
Expand Down