CherryHQ/cherry-studio · error · Error

[theme-contract] variable catalog is missing: ${missing.join

Error message

[theme-contract] variable catalog is missing: ${missing.join(', ')}

What it means

Thrown by assertCatalogCoverage when the documentation file docs/variable-catalog.md does not contain a backtick-quoted mention of every required contract variable (all runtime inputs, Shadcn variables, and product variables). The catalog is the public documentation surface; the validator guarantees it stays in sync with the code-defined registries so no variable ships undocumented.

Source

Thrown at packages/ui/scripts/validate-theme-contract.ts:303

      const validNamespace =
        reference.startsWith('--cs-') || officialVariables.has(reference) || productVariables.has(reference)
      if (!validNamespace) {
        throw new Error(`[theme-contract] product ${declaration.name} has invalid dependency ${reference}`)
      }
    }
  }
}

function assertCatalogCoverage(sources: ThemeContractSources): void {
  const requiredNames = [
    ...RUNTIME_THEME_INPUT_TOKENS.map((token) => `--cs-theme-${token}`),
    ...SHADCN_VARIABLE_TOKENS.map((token) => `--${token}`),
    ...CHERRY_PRODUCT_VARIABLE_TOKENS.map((token) => `--${token}`)
  ]
  const missing = requiredNames.filter((name) => !sources.variableCatalog.includes(`\`${name}\``))

  if (missing.length > 0) {
    throw new Error(`[theme-contract] variable catalog is missing: ${missing.join(', ')}`)
  }
}

export function validateThemeContractSources(sources: ThemeContractSources): void {
  assertUnique('runtime theme inputs', RUNTIME_THEME_INPUT_TOKENS)
  assertUnique('Shadcn variables', SHADCN_VARIABLE_TOKENS)
  assertUnique('product variables', CHERRY_PRODUCT_VARIABLE_TOKENS)
  assertUnique('Tailwind product colors', CHERRY_PRODUCT_COLOR_TOKENS)
  assertUnique('compatibility semantic colors', COMPATIBILITY_SEMANTIC_COLOR_TOKENS)
  assertUnique('compatibility status colors', COMPATIBILITY_STATUS_COLOR_TOKENS)
  assertUnique('compatibility colors', COMPATIBILITY_COLOR_TOKENS)

  const productVariables = new Set<string>(CHERRY_PRODUCT_VARIABLE_TOKENS)
  const shadcnVariables = new Set<string>(SHADCN_VARIABLE_TOKENS)
  const shadcnVariableNames = new Set<string>(SHADCN_VARIABLE_TOKENS.map((token) => `--${token}`))
  const productVariableNames = new Set<string>(CHERRY_PRODUCT_VARIABLE_TOKENS.map((token) => `--${token}`))
  const canonicalColors = new Set<string>([...SHADCN_COLOR_TOKENS, ...CHERRY_PRODUCT_COLOR_TOKENS])

View on GitHub (pinned to 726446b54c)

Solutions

1. Open packages/ui/docs/variable-catalog.md and add each missing variable as a backtick-quoted literal exactly as listed (e.g. `--success`).
2. Verify the spelling matches the message character-for-character (the check searches for the exact `${name}` inside backticks).
3. Re-run `pnpm --filter @cherrystudio/ui theme:check`.

Example fix

// before — variable-catalog.md is missing `--success`
// after
| success | `--success` | product feedback success |

// Verify every required name appears backtick-quoted in the catalog before validating.
const required = [...RUNTIME_THEME_INPUT_TOKENS.map((t) => `--cs-theme-${t}`), ...SHADCN_VARIABLE_TOKENS.map((t) => `--${t}`), ...CHERRY_PRODUCT_VARIABLE_TOKENS.map((t) => `--${t}`)]
const missing = required.filter((n) => !sources.variableCatalog.includes(``${n}``))
if (missing.length) throw new Error(`catalog missing: ${missing.join(', ')}`)

try {
  validateThemeContractSources(sources)
} catch (error) {
  if (error instanceof Error && /variable catalog is missing/.test(error.message)) {
    console.error(error.message)
    process.exitCode = 1
    return
  }
  throw error
}

When it happens

Trigger: Adding a token to SHADCN_VARIABLE_TOKENS, CHERRY_PRODUCT_VARIABLE_TOKENS, or RUNTIME_THEME_INPUT_TOKENS in scripts/theme-contract.ts without adding a matching `--name` entry in packages/ui/docs/variable-catalog.md; editing the catalog and dropping a line.

Common situations: Extending the contract with a new role and forgetting to document it; regenerated/edited catalog that lost entries.

Related errors

• [theme-contract] ${declaration.name} is defined twice in ${s
• [theme-contract] ${label} is missing root declarations: ${mi
• [theme-contract] ${label} references missing foundation vari
• [theme-contract] ${mode} ${declaration.name} in ${declaratio
• [theme-contract] ${mode} variable cycle: ${[...stack.slice(c

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