chatboxai/chatbox · warning · ChatboxCliUsageError

Unknown or protected setting: ${key}

Error message

Unknown or protected setting: ${key}

What it means

Thrown by findSetting() in the CLI settings module when the requested key does not match any entry in the safeSettings allowlist. The allowlist is an explicit, hand-curated set of read-only settings; anything not on it (including write-protected/internal keys) is refused to prevent the CLI from reading sensitive or unsupported state.

Source

Thrown at src/renderer/packages/chatbox-cli/settings.ts:116

    read: () => settingsStore.getState().messageLayout ?? 'bubble',
  },
  {
    key: 'chat.compaction-threshold',
    description: 'Context compaction threshold.',
    page: 'Chat Settings',
    read: () => settingsStore.getState().compactionThreshold,
  },
  {
    key: 'app.startup-page',
    description: 'Page shown at startup.',
    page: 'General Settings',
    read: () => settingsStore.getState().startupPage ?? 'home',
  },
]

function findSetting(key: string): SafeSettingSpec {
  const setting = safeSettings.find((candidate) => candidate.key === key)
  if (!setting) throw new ChatboxCliUsageError(`Unknown or protected setting: ${key}`)
  return setting
}

export const settingsCommands: ChatboxCliCommandDefinition[] = [
  {
    path: ['settings', 'list'],
    description: 'List settings exposed through the read-only CLI allowlist.',
    usage: 'chatbox settings list',
    execute() {
      return {
        readOnly: true,
        changeGuidance: 'Guide the user to the listed Chatbox Settings page to make changes manually.',
        settings: safeSettings.map((setting) => ({
          key: setting.key,
          value: setting.read(),
          description: setting.description,
          location: `Settings > ${setting.page}`,
        })),

View on GitHub (pinned to 81571269ad)

Solutions

1. Run `chatbox settings list` to see every key the CLI actually exposes, then copy the exact key.
2. Check the dot-namespace and casing against the listed key precisely.
3. If the key is legitimately missing, it must be added to the safeSettings array in settings.ts before the CLI can read it — this is intentional, not a bug.

Example fix

// before
chatbox settings get app.startUp-page

// after
chatbox settings get app.startup-page

const KNOWN_KEYS = safeSettings.map(s => s.key)
if (!KNOWN_KEYS.includes(requestedKey)) {
  // show `chatbox settings list` instead of calling get
}

function isKnownSettingKey(key: string): boolean {
  return safeSettings.some(s => s.key === key)
}

try {
  await runSettingsGet(key)
} catch (e) {
  if (e instanceof ChatboxCliUsageError && /Unknown or protected/.test(e.message)) {
    // offer `settings list` to the user
  }
  throw e
}

When it happens

Trigger: Running `chatbox settings get <key>` where <key> is misspelled, uses the wrong dot-namespace, or refers to a setting that exists in the app but was deliberately excluded from safeSettings. The lookup is an exact-string match against candidate.key.

Common situations: Typo in the key (e.g. 'app.startUp-page' vs 'app.startup-page'); guessing a key name from the UI that the CLI never exposed; version drift where a setting was renamed or removed from the allowlist in a newer build.

Related errors

• Missing setting key.
• Custom provider "${providerId}" conflicts with a builtin pro
• Invalid settings entry
• --${name} must be an integer.
• --${name} must be between ${options.min} and ${options.max}.

AI-assisted analysis of chatboxai/chatbox@81571269ad (2026-08-12). Data as JSON: /api/errors/5eb2e6fba7af0eac. Report an issue: GitHub.