block/buzz · error · AgentError

Databricks v2 model discovery failed: workspace endpoint cat

Error message

Databricks v2 model discovery failed: workspace endpoint catalog: {workspace}; Unity Catalog model-service catalog: {unity_catalog}

What it means

`combined_catalog_error` merges two independent Databricks v2 model-discovery failures (the workspace endpoint catalog fetch and the Unity Catalog model-service catalog fetch) into a single AgentError. The message embeds both underlying errors; if either source error is `AgentError::LlmAuth`, the combined error is classified as `LlmAuth` (auth problem), otherwise a plain `Llm` error. It is raised by `fetch_v2_models_with_policy` when both discovery paths fail.

Source

Thrown at crates/buzz-agent/src/catalog.rs:398

}

fn catalog_error_kind(error: &AgentError) -> &'static str {
    match error {
        AgentError::InvalidParams(_) => "invalid-params",
        AgentError::Llm(_) => "llm",
        AgentError::LlmAuth(_) => "auth",
        AgentError::LlmModelNotFound(_) => "model-not-found",
        AgentError::LlmContextExceeded(_) => "context-exceeded",
        AgentError::UnsupportedImageInput(_) => "unsupported-image",
        AgentError::Mcp(_) => "mcp",
        AgentError::Cancelled => "cancelled",
    }
}

fn combined_catalog_error(workspace: AgentError, unity_catalog: AgentError) -> AgentError {
    let auth_failure = matches!(&workspace, AgentError::LlmAuth(_))
        || matches!(&unity_catalog, AgentError::LlmAuth(_));
    let message = format!(
        "Databricks v2 model discovery failed: workspace endpoint catalog: {workspace}; Unity Catalog model-service catalog: {unity_catalog}"
    );
    if auth_failure {
        AgentError::LlmAuth(message)
    } else {
        AgentError::Llm(message)
    }
}

fn merge_v2_models(
    workspace: Vec<V2Endpoint>,
    mut unity_catalog: Vec<ModelEntry>,
    filter: Option<&DatabricksModelFilter>,
    allow_known_model_fallback: bool,
) -> Vec<ModelEntry> {
    let mut seen_ids = HashSet::new();
    let mut merged = Vec::with_capacity(workspace.len() + unity_catalog.len());

View on GitHub (pinned to dad5a33865)

Solutions

Check the embedded sub-errors: if either mentions auth/401/403, refresh the Databricks token or service-principal credentials first.
Verify DATABRICKS_HOST and the workspace URL are correct and reachable (curl the /api/2.0/serving-endpoints endpoint).
Grant the token's principal permission to list serving endpoints and to the target Unity Catalog model catalog/schema.
Check network egress/proxy settings; both catalogs failing together usually indicates connectivity, not per-model config.
If permissions are fine, confirm the Databricks API responses haven't changed shape (SDK version drift).

Example fix

// before
let token = std::env::var("DATABRICKS_TOKEN")?; // expired or empty -> both catalogs 401
// after
let token = std::env::var("DATABRICKS_TOKEN")?;
if token.is_empty() {
    return Err(AgentError::LlmAuth("DATABRICKS_TOKEN is empty; refresh credentials before model discovery".into()));
}
// probe auth early so discovery reports one clear cause:
client.list_serving_endpoints().await.map_err(|e| AgentError::LlmAuth(format!("databricks auth probe failed: {e}")))?;

Defensive patterns

Strategy: validation

Validate before calling

// validate Databricks config and auth before model discovery
let token = std::env::var("DATABRICKS_TOKEN").map_err(|_| "DATABRICKS_TOKEN not set")?;
let host = std::env::var("DATABRICKS_HOST").map_err(|_| "DATABRICKS_HOST not set")?;
assert!(!token.is_empty() && host.starts_with("https://"), "valid DATABRICKS_HOST (https://...) and non-empty DATABRICKS_TOKEN required");
// auth probe
client.list_serving_endpoints().await.map_err(|e| format!("databricks auth probe failed: {e}"))?;

Try / catch

match fetch_v2_models_with_policy(...).await {
    Err(e @ AgentError::LlmAuth(msg)) => { /* refresh token / fix permissions; msg names both catalog errors */ },
    Err(e @ AgentError::Llm(msg)) => { /* connectivity or API-shape issue; check network and SDK version */ },
    Ok(models) => use(models),
}

Prevention

Refresh Databricks tokens on a schedule before they expire.
Verify the service principal can list both serving endpoints and Unity Catalog models.
Probe the workspace API at startup and fail fast with a clear auth message.
Check corporate proxy/egress rules for Databricks workspace hosts.

When it happens

Trigger: Calling Databricks model discovery when the workspace serving-endpoint list API fails AND the Unity Catalog model-service list fails — e.g. expired/missing Databricks token, wrong workspace URL, network egress blocked, or the catalog/schema does not exist for this token.

Common situations: Expired PAT/OAuth token (yields LlmAuth classification), misconfigured DATABRICKS_HOST or workspace URL, service principal lacking permissions on unity_catalog models, corporate proxy blocking the workspace endpoint, or Databricks API version drift.

Related errors

AI-assisted analysis of block/buzz@dad5a33865 (2026-08-30). Data as JSON: /api/errors/6e8909ddd952ee11. Report an issue: GitHub.