What causes "failed to configure providers: %w" in charmbracelet/crush?

Inspect the wrapped %w error for the root cause (usually a specific provider or header)

failed to configure providers: %w

Error message

failed to configure providers: %w

What it means

Load() calls cfg.configureProviders() to resolve provider credentials, headers, and metadata from catwalk/known providers. Any failure inside that pipeline (env resolution, header resolution, model fetching) is wrapped as 'failed to configure providers'.

Source

Thrown at internal/config/load.go:134

	}
	store.knownProviders = providers

	env := env.New()
	// Configure providers
	valueResolver := NewShellVariableResolver(env)
	store.resolver = valueResolver

	// Hold writeMu during initial load to prevent configureProviders
	// from triggering auto-reload via RemoveConfigField.
	store.writeMu.Lock()
	defer store.writeMu.Unlock()

	// Apply top-level env vars before configuring providers so variables
	// like AWS_PROFILE are visible to the AWS SDK credential chain.
	cfg.applyEnv(valueResolver)

	if err := cfg.configureProviders(context.Background(), store, env, valueResolver, store.knownProviders); err != nil {
		return nil, fmt.Errorf("failed to configure providers: %w", err)
	}

	if !cfg.IsConfigured() {
		slog.Warn("No providers configured")
		return store, nil
	}

	resolved, err := resolveSelectedModels(cfg, store.knownProviders)
	if err != nil {
		return nil, fmt.Errorf("failed to configure selected models: %w", err)
	}
	cfg.Models[SelectedModelTypeLarge] = resolved.Large
	cfg.Models[SelectedModelTypeSmall] = resolved.Small

	// Persist any fallback corrections while we still hold writeMu.
	if resolved.LargeFallback {
		if err := store.updateLocked(ScopeGlobal, func(c *Config) map[string]any {
			return store.updatePreferredModelFields(c, SelectedModelTypeLarge, resolved.Large)

View on GitHub (pinned to 7944b8e522)

Solutions

Inspect the wrapped %w error for the root cause (usually a specific provider or header)
Set the required environment variables (API keys, AWS_PROFILE) before starting
Fix or remove the offending provider entry in crush.json/crushrc
Check network/credential access if the root cause is provider metadata fetching

Example fix

// before
export ANTHROPIC_API_KEY=
crush  // failed to configure providers: ...
// after
export ANTHROPIC_API_KEY=sk-ant-...
crush

Defensive patterns

Strategy: try-catch

Validate before calling

for _, key := range requiredEnvVars() { // e.g. AWS_PROFILE, provider API keys
    if os.Getenv(key) == "" {
        return fmt.Errorf("required env var %s is not set", key)
    }
}

Try / catch

store, err := config.Load(ctx, opts)
if err != nil {
    if strings.Contains(err.Error(), "failed to configure providers:") {
        return fmt.Errorf("check provider credentials/env: %w", err)
    }
    return err
}

Prevention

Export provider API keys and AWS profile in shell profile or .env loaded before launch
Use options.env in config to pin required env vars
Keep provider configs minimal and validate with a test run after changes
Match SDK requirements (Bedrock needs full AWS credential chain)

When it happens

Trigger: cfg.configureProviders returns an error — e.g. a provider header env var fails to resolve, required cloud credentials (AWS/Bedrock) are missing, or provider metadata cannot be loaded.

Common situations: Missing AWS_PROFILE or AWS credentials for Bedrock; an API-key env var unset where resolution is strict; corrupted provider section in config; catwalk provider catalog unavailable.

Related errors

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/8b413cd80d7db6cc. Report an issue: GitHub.