{"record":{"id":"988f24ad33f62dd8","repo":"sipeed/picoclaw","slug":"failed-to-initialize-model-q-w","errorCode":null,"errorMessage":"failed to initialize model %q: %w","messagePattern":"failed to initialize model %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/agent_command.go","lineNumber":308,"sourceCode":"\t\treturn al.reloadFunc()\n\t}\n\tif agent != nil {\n\t\tif agent.ContextBuilder != nil {\n\t\t\trt.ListSkillNames = agent.ContextBuilder.ListSkillNames\n\t\t}\n\t\trt.GetModelInfo = func() (string, string) {\n\t\t\treturn agent.Model, resolvedCandidateProvider(agent.Candidates, cfg.Agents.Defaults.Provider)\n\t\t}\n\t\trt.SwitchModel = func(value string) (string, error) {\n\t\t\tvalue = strings.TrimSpace(value)\n\t\t\tmodelCfg, err := resolvedModelConfig(cfg, value, agent.Workspace)\n\t\t\tif err != nil {\n\t\t\t\treturn \"\", err\n\t\t\t}\n\n\t\t\tnextProvider, _, err := providers.CreateProviderFromConfig(modelCfg)\n\t\t\tif err != nil {\n\t\t\t\treturn \"\", fmt.Errorf(\"failed to initialize model %q: %w\", value, err)\n\t\t\t}\n\n\t\t\tnextCandidates := resolveModelCandidates(cfg, cfg.Agents.Defaults.Provider, value, agent.Fallbacks)\n\t\t\tif len(nextCandidates) == 0 {\n\t\t\t\treturn \"\", fmt.Errorf(\"model %q did not resolve to any provider candidates\", value)\n\t\t\t}\n\n\t\t\toldModel := agent.Model\n\t\t\toldProvider := agent.Provider\n\t\t\tagent.Model = value\n\t\t\tagent.Provider = nextProvider\n\t\t\tagent.Candidates = nextCandidates\n\t\t\tagent.ThinkingLevel = parseThinkingLevel(modelCfg.ThinkingLevel)\n\t\t\tagent.ThinkingLevelConfigured = isConfiguredThinkingLevel(modelCfg.ThinkingLevel)\n\n\t\t\tif oldProvider != nil && oldProvider != nextProvider {\n\t\t\t\tif stateful, ok := oldProvider.(providers.StatefulProvider); ok {\n\t\t\t\t\tstateful.Close()","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/sipeed/picoclaw/blob/49183d7e8daed0dba89ddbb6fcb60089401d9680/pkg/agent/agent_command.go#L290-L326","documentation":"Raised by the SwitchModel hook: the requested model resolved to a config entry (resolvedModelConfig succeeded), but providers.CreateProviderFromConfig failed to construct a live provider from it. The %w wraps the provider-layer cause: unsupported provider type, missing/invalid API key, malformed base URL, or bad provider-specific settings. The old model/provider are left untouched — switching is atomic on failure.","triggerScenarios":"`/model <name>` where the model's provider config lacks an API key, references an unknown provider kind, or carries an invalid endpoint; environment variable for the key unset; provider plugin/SDK initialization error.","commonSituations":"Adding a new model to config without credentials; expired or revoked API keys; renaming a provider in config after an upgrade; typos in base_url or model fields; air-gapped host failing a provider that phones home at init.","solutions":["Read the wrapped cause in the message — it names the exact provider failure (auth, unsupported type, URL)","Fix the model's config block: correct provider name, valid API key/env var reference, sane base URL","Verify the key works outside picoclaw (curl the provider endpoint) then retry /model","Stay on the previous model — it remains active since the switch aborted"],"exampleFix":"# before\nmodels:\n  fast:\n    provider: openai      # key never set\n\n# after\nexport OPENAI_API_KEY=sk-...\n# or in config:\nmodels:\n  fast:\n    provider: openai\n    api_key: ${OPENAI_API_KEY}","handlingStrategy":"try-catch","validationCode":"// Pre-flight the exact same construction the hook performs:\nmodelCfg, err := resolvedModelConfig(cfg, value, agent.Workspace)\nif err != nil { /* invalid name: reject before switching */ }\nif _, _, err := providers.CreateProviderFromConfig(modelCfg); err != nil {\n    /* provider init fails: show wrapped cause, do not offer switch */\n}","typeGuard":null,"tryCatchPattern":"_, err := rt.SwitchModel(value)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to initialize model\") {\n        // unwrap %w: auth/URL/provider-type errors — fix config/key, retry; current model is unchanged\n    }\n}","preventionTips":["Dry-run providers.CreateProviderFromConfig before offering a model switch","Validate provider credentials at startup, not only at switch time","Rely on the abort-on-failure semantics: agent.Model is untouched when this fires"],"tags":["model","provider","configuration","authentication"],"backgroundTag":null,"analyzedSha":"49183d7e8daed0dba89ddbb6fcb60089401d9680","analyzedAt":"2026-08-15T21:55:41.315Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}