CherryHQ/cherry-studio · error · ProviderCreationError

Failed to create provider "${id}"

Error message

Failed to create provider "${id}"

What it means

Raised by improve_description.py after invoking the `claude -p` (print mode) CLI as a subprocess and receiving a non-zero exit code. The error message embeds the return code and stderr so the underlying CLI failure is visible. The script strips the CLAUDECODE env var before launching to avoid nested-session detection, which can itself be a cause if the CLI relies on it. The subprocess runs with text capture and a timeout.

Source

Thrown at packages/aiCore/src/core/providers/core/ExtensionRegistry.ts:504

  async createProvider<T extends RegisteredProviderId>(id: T, settings: CoreProviderSettingsMap[T]): Promise<ProviderV3>
  async createProvider(id: string, settings?: unknown): Promise<ProviderV3>
  async createProvider(id: string, settings?: unknown): Promise<ProviderV3> {
    const parsed = this.parseProviderId(id)
    if (!parsed) {
      throw new Error(`Provider extension "${id}" not found. Did you forget to register it?`)
    }

    const { baseId, mode: variantSuffix } = parsed

    const extension = this.get(baseId)
    if (!extension) {
      throw new Error(`Provider extension "${baseId}" not found. Did you forget to register it?`)
    }

    try {
      return await extension.createProvider(settings, variantSuffix)
    } catch (error) {
      throw new ProviderCreationError(
        `Failed to create provider "${id}"`,
        id,
        error instanceof Error ? error : new Error(String(error))
      )
    }
  }
}

/**
 * 全局 Extension Registry 实例
 * 单例模式，确保整个应用只有一个注册表
 */
export const extensionRegistry = new ExtensionRegistry()

View on GitHub (pinned to 726446b54c)

Solutions

1. Confirm `claude` is installed and on PATH: run `claude --version` in the same shell/env.
2. Authenticate the CLI (`claude` interactive login / set the required API key) before running the script.
3. Read the embedded stderr in the RuntimeError — it states the CLI's own failure reason.
4. Increase the timeout argument passed to improve_description if the call is timing out.
5. Verify the model string passed to the script is a valid, accessible model id for the CLI.

Example fix

# before
improve_description(..., model='claude-nonexistent', timeout=10)
# after
# 1) ensure CLI is available and authenticated
#    $ claude --version && claude   # log in interactively once
# 2) call with a valid model and a roomier timeout
improve_description(..., model='claude-sonnet-4-5', timeout=120)

# Validate the CLI is reachable and authenticated before calling improve_description.
import shutil, subprocess
def ensure_claude_cli() -> None:
    if not shutil.which('claude'):
        raise RuntimeError('claude CLI not found on PATH; install and authenticate it first')
    # quick auth/health check
    subprocess.run(['claude', '--version'], check=True, capture_output=True)

try:
    improved = improve_description(...)
except RuntimeError as e:
    if 'claude -p exited' in str(e):
        # CLI-level failure: report stderr to the user, do not swallow
        raise SystemExit(f'Claude CLI failed during description improvement:\n{e}') from e
    raise

When it happens

Trigger: `claude` is not installed or not on PATH (returncode 127); CLAUDECODE removal or missing auth causes the CLI to exit non-zero; the prompt/model arg is invalid; the call exceeded the timeout (subprocess.TimeoutExpired is a separate exception, but a CLI that hits its own internal limit returns non-zero); API rate limit or network failure surfaced by the CLI as a non-zero exit.

Common situations: Running the skill-creator improve script in an environment without the Claude CLI installed; auth not configured (claude not logged in); the configured model is unavailable/disabled; the timeout passed to improve_description is too short for a large skill; running inside a container where PATH differs.

Related errors

• Provider extension "${baseId}" not found. Did you forget to
• OpenAI Compatible provider requires settings
• ${effectiveCommand} not found in PATH and bundled version is
• npx not found in PATH and bundled bun is not available. This

AI-assisted analysis of CherryHQ/cherry-studio@726446b54c (2026-08-12). Data as JSON: /api/errors/a5cb8d6e63c4b093. Report an issue: GitHub.