What causes "Model probe failed for target model_provider" in zeroclaw-labs/zeroclaw?

Check the provider's api_key is set and valid in the daemon's environment

zeroclaw-labs/zeroclaw · error · anyhow::Error

Model probe failed for target model_provider

Error message

Model probe failed for target model_provider

What it means

After probing, run_models counts successful targets; when a specific provider override was supplied and ok_count == 0, every probe for that provider failed (auth, endpoint, network, or plan access) and the command exits with this error instead of reporting success. The per-target failure details are printed above the bail, including a hint about API keys/plan access.

Source

Thrown at crates/zeroclaw-runtime/src/doctor/mod.rs:672

                .unwrap_or_else(|| "-".to_string());
            println!(
                "  {:<18} {:<12} {:<8} {}",
                model_provider,
                model_probe_status_label(outcome),
                models_text,
                detail
            );
        }
    }

    if auth_count > 0 {
        println!(
            "  💡 Some model_providers need valid API keys/plan access before `/models` can be fetched."
        );
    }

    if provider_override.is_some() && ok_count == 0 {
        anyhow::bail!("Model probe failed for target model_provider")
    }

    Ok(())
}

/// Function type for fetching context window from provider.
/// Allows injection of mock fetch for testing.
type FetchContextWindowFn = Box<
    dyn for<'a> Fn(
            &'a str,
            &'a zeroclaw_config::schema::ModelProviderConfig,
        ) -> std::pin::Pin<
            Box<dyn std::future::Future<Output = Option<usize>> + Send + 'a>,
        > + Send
        + Sync,
>;

/// Update context_window in config.toml from provider /models endpoints.

View on GitHub (pinned to 88bb9c8533)

Solutions

Check the provider's api_key is set and valid in the daemon's environment
Verify the provider URI is reachable (curl its /models endpoint)
Re-run without the provider filter and read the per-target error lines to isolate the cause
Confirm the account/plan exposes the model-list endpoint

Defensive patterns

Strategy: try-catch

Validate before calling

let entry = config.providers.models.get(alias)
    .ok_or_else(|| anyhow::anyhow!("unknown provider alias '{alias}'"))?;
if entry.api_key.as_deref().map(str::trim).unwrap_or("").is_empty() {
    anyhow::bail!("provider '{alias}' has no api_key set — probes will fail");
}

Try / catch

match zeroclaw_runtime::doctor::run_models(&config, Some(&alias), false, false).await {
    Err(err) if err.to_string().contains("Model probe failed") => {
        eprintln!("all probes for '{alias}' failed — check api_key, endpoint URI, and network egress");
    }
    other => other?,
}

Prevention

Rotate keys in config before the old one expires, and keep the daemon environment in sync
Smoke-test provider endpoints with a direct curl to /models when probes start failing
Run the unfiltered probe periodically to distinguish provider-wide outages from per-provider key issues

When it happens

Trigger: Doctor models probe scoped to one provider (--provider <alias>) where the API key is invalid or expired, the endpoint URI is unreachable, or the account cannot list /models.

Common situations: Expired or rotated API key not updated in config/env; self-hosted endpoint URL typo; proxy or firewall blocking egress; free-plan accounts that restrict model listing.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/469312a4023b2bf1. Report an issue: GitHub.