NousResearch/hermes-agent · error

"${theme.name}" collides with a built-in theme.

Error message

"${theme.name}" collides with a built-in theme.

What it means

Thrown by installUserTheme when the theme's name matches a built-in theme (BUILTIN_THEMES lookup by name). User themes are stored keyed by name alongside built-ins; allowing a collision would let an installed theme shadow or be confused with a built-in, so installation is refused before any state or localStorage write.

Source

Thrown at apps/desktop/src/themes/user-themes.ts:92

    return {}
  }
}

function persist(record: Record<string, DesktopTheme>) {
  try {
    window.localStorage.setItem(USER_THEMES_KEY, JSON.stringify(record))
  } catch {
    // Best-effort: a restricted storage context shouldn't break theming.
  }
}

/** Reactive map of installed user themes, keyed by slug. */
export const $userThemes = atom<Record<string, DesktopTheme>>(typeof window === 'undefined' ? {} : readStored())

/** Install (or replace) a user theme. Returns the stored theme. */
export function installUserTheme(theme: DesktopTheme): DesktopTheme {
  if (BUILTIN_THEMES[theme.name]) {
    throw new Error(`"${theme.name}" collides with a built-in theme.`)
  }

  if (!isValidTheme(theme)) {
    throw new Error('Theme is missing required colors.')
  }

  const next = { ...$userThemes.get(), [theme.name]: theme }
  $userThemes.set(next)
  persist(next)

  return theme
}

/** Remove a user theme by slug. No-op for unknown / built-in names. */
export function removeUserTheme(name: string): void {
  const current = $userThemes.get()

  if (!current[name]) {

View on GitHub (pinned to c896c09c42)

Solutions

1. Rename the theme (its name field / label) to something unique before installing.
2. If you want to override a built-in look, create a copy with a distinct name and edit its colors.
3. Pre-check BUILTIN_THEMES[theme.name] in your own code and prompt for a new name.

Example fix

// before
installUserTheme({ ...theme, name: 'slate' })

// after
installUserTheme({ ...theme, name: 'slate-custom' })

import { BUILTIN_THEMES } from '.../themes'

function isNameFree(name: string): boolean {
  return !BUILTIN_THEMES[name]
}

function isInstallableName(name: string): boolean {
  return !BUILTIN_THEMES[name]
}

try {
  installUserTheme(theme)
} catch (e) {
  if (e instanceof Error && e.message.includes('collides with a built-in'))
    promptRename(theme)
  else throw e
}

When it happens

Trigger: Installing a user/imported theme whose name field equals a built-in theme name (e.g. a converted VS Code theme labeled 'default', 'mono', 'slate', or 'ares').

Common situations: Importing a VS Code theme whose display name happens to match a Hermes built-in, or a custom JSON theme copied from a built-in without renaming.

Related errors

• Expected a Marketplace id like "publisher.extension".
• Theme is missing required colors.
• Branch name is required.
• Missing URL
• Invalid data URL

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/297e9ed50180cccf. Report an issue: GitHub.