needs_quickstart: gateway booted without a working model_pro

Error message

needs_quickstart: gateway booted without a working model_provider. Complete browser quickstart at /quickstart, or fix [providers.models.<type>.<alias>] and POST /admin/reload.

What it means

The gateway boots with an `UnconfiguredModelProvider` placeholder when no usable model provider could be built from configuration. Every `chat_with_system` call on that placeholder bails with `needs_quickstart`, directing the operator to the browser quickstart at `/quickstart` or to fix the `[providers.models.<type>.<alias>]` config section and then `POST /admin/reload`. It means the gateway process is healthy but has no LLM backend wired.

Source

Thrown at crates/zeroclaw-gateway/src/lib.rs:2416

}

/// Result of a gateway chat turn.
struct GatewayChatOutcome {
    response: String,
}

struct UnconfiguredModelProvider;

#[async_trait::async_trait]
impl ModelProvider for UnconfiguredModelProvider {
    async fn chat_with_system(
        &self,
        _system_prompt: Option<&str>,
        _message: &str,
        _model: &str,
        _temperature: Option<f64>,
    ) -> anyhow::Result<String> {
        anyhow::bail!(
            "needs_quickstart: gateway booted without a working model_provider. \
             Complete browser quickstart at /quickstart, or fix \
             [providers.models.<type>.<alias>] and POST /admin/reload."
        )
    }
}

impl ::zeroclaw_api::attribution::Attributable for UnconfiguredModelProvider {
    fn role(&self) -> ::zeroclaw_api::attribution::Role {
        ::zeroclaw_api::attribution::Role::Provider(
            ::zeroclaw_api::attribution::ProviderKind::Model(
                ::zeroclaw_api::attribution::ModelProviderKind::Custom,
            ),
        )
    }
    fn alias(&self) -> &str {
        "unconfigured"
    }

View on GitHub (pinned to 88bb9c8533)

Solutions

Open the gateway's `/quickstart` page in a browser and complete provider setup
Fix or add `[providers.models.<type>.<alias>]` in config.toml, then `POST /admin/reload` (no restart needed)
Check gateway startup logs for why the configured provider failed to build, fix that root cause, then reload

Example fix

# before — config.toml has no provider section
# after
[providers.models.openai.gpt-4o-mini]
api_key = "sk-your-key"
# then: curl -X POST http://127.0.0.1:8080/admin/reload

Defensive patterns

Strategy: try-catch

Validate before calling

// Before wiring channels that will chat, smoke-test the provider:
if let Err(e) = gateway.chat_with_system(None, "ping", &default_model, None).await {
    if e.to_string().starts_with("needs_quickstart") {
        eprintln!("complete /quickstart or fix [providers.models.*] before use");
    }
    return Err(e);
}

Try / catch

match provider.chat_with_system(None, msg, model, temp).await {
    Err(e) if e.to_string().starts_with("needs_quickstart") => {
        // Configuration problem, not a transient failure: direct the user to setup.
        return Ok(render_setup_required_response());
    }
    other => other,
}

Prevention

Complete /quickstart before connecting channels that trigger chat
After every config.toml provider edit, POST /admin/reload and run a one-message smoke test
Watch gateway boot logs for provider-construction failures that fall back to the placeholder

When it happens

Trigger: Fresh install with no provider configured; a `[providers.models...]` entry that failed to build (bad API key, unknown provider type); any chat request routed to the gateway before a working provider exists.

Common situations: First boot before completing browser quickstart; editing config.toml with a schema or syntax error that makes provider construction fall back to the placeholder; renaming or deleting a model alias while channels still reference it.

Related errors

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