CherryHQ/cherry-studio · error · Error

OpenAI Compatible provider requires settings

Error message

OpenAI Compatible provider requires settings

What it means

Raised by parse_skill_md() when the first line of a SKILL.md file is not exactly '---' (after strip). The parser expects YAML frontmatter delimited by opening and closing '---' lines; an absent opening delimiter means there is no frontmatter block to read name/description from. This fails fast rather than mis-parsing the body as frontmatter.

Source

Thrown at packages/aiCore/src/core/providers/core/initialization.ts:176

    webSearch:
      (provider: GoogleGenerativeAIProvider) =>
      (config: NonNullable<Parameters<GoogleGenerativeAIProvider['tools']['googleSearch']>[0]>) => ({
        tools: { webSearch: provider.tools.googleSearch(config) }
      }),
    urlContext: (provider) => (config) => ({
      tools: {
        urlContext: provider.tools.urlContext(config)
      }
    })
  }
} as const satisfies ProviderExtensionConfig<GoogleGenerativeAIProviderSettings, GoogleGenerativeAIProvider, 'google'>)

const OpenAICompatibleExtension = ProviderExtension.create({
  name: 'openai-compatible',
  supportsImageGeneration: true,
  create: (settings) => {
    if (!settings) {
      throw new Error('OpenAI Compatible provider requires settings')
    }
    return createOpenAICompatible(settings)
  },
  createRerankingModel: (modelId, settings) => {
    if (!settings) {
      throw new Error('OpenAI Compatible provider requires settings')
    }
    return createOpenAICompatibleRerankingModel(modelId, settings)
  }
} as const satisfies ProviderExtensionConfig<OpenAICompatibleProviderSettings, ProviderV3, 'openai-compatible'>)

const OpenAIExtension = ProviderExtension.create({
  name: 'openai',
  aliases: ['openai-response'] as const,
  supportsImageGeneration: true,
  create: createOpenAI,
  toolFactories: {
    webSearch:

View on GitHub (pinned to 726446b54c)

Solutions

1. Add YAML frontmatter beginning with a '---' line as the very first line of SKILL.md.
2. Include the required keys (name:, description:) between the opening and closing '---'.
3. Ensure the file is saved as UTF-8 without BOM so the first line matches '---'.
4. Use the skill-creator scaffolding to generate a valid SKILL.md skeleton.

Example fix

# before
# My Cool Skill

Does cool things.
# after
---
name: my-cool-skill
description: Does cool things.
---

# My Cool Skill

# Validate SKILL.md frontmatter structure before parsing.
from pathlib import Path
def has_frontmatter(skill_path: Path) -> bool:
    text = (skill_path / 'SKILL.md').read_text(encoding='utf-8-sig')  # strip BOM
    lines = text.split('\n')
    return len(lines) > 0 and lines[0].strip() == '---' and any(l.strip() == '---' for l in lines[1:])

def starts_with_frontmatter(path: Path) -> bool:
    first = (path / 'SKILL.md').read_text(encoding='utf-8-sig').split('\n', 1)[0].strip()
    return first == '---'

from utils import parse_skill_md
try:
    name, desc, content = parse_skill_md(skill_path)
except ValueError as e:
    if 'opening ---' in str(e):
        print(f'{skill_path}: no frontmatter — add a leading --- block (name, description)')
    raise

When it happens

Trigger: A SKILL.md starts with prose (e.g. a title '# My Skill') and has no frontmatter; the file begins with a UTF-8 BOM so the first line is not literally '---'; the file is empty; the file uses a different delimiter (e.g. '+++').

Common situations: A skill hand-authored without frontmatter; a file copied from a Markdown template that begins with a heading; an editor saving with a BOM; a skill partially generated where the frontmatter was not written.

Related errors

• Provider extension "${baseId}" not found. Did you forget to
• Failed to create provider "${id}"
• ${effectiveCommand} not found in PATH and bundled version is

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