What causes "Use a string array or null." in stablyai/orca?

Pass bindings as string[] (e.g. ['Cmd+K']) or null to clear.

stablyai/orca · error · Error

Use a string array or null.

Error message

Use a string array or null.

What it means

Thrown by normalizeWriteBindingValue when the value passed to a keybinding write is not null and not an array of strings. This is the strict write path (Settings UI): it accepts only string[] or null, unlike the read/parse path which also tolerates a single string, false, etc.

Source

Thrown at src/main/keybindings/keybinding-file.ts:120

    if (!value.every((item) => typeof item === 'string')) {
      return { ok: false, error: 'Use a string, string array, null, or false.' }
    }
    const normalized = normalizeKeybindingArrayForAction(actionId, value)
    return Array.isArray(normalized)
      ? { ok: true, value: normalized }
      : normalized.ok
        ? { ok: true, value: [normalized.value] }
        : normalized
  }
  return { ok: false, error: 'Use a string, string array, null, or false.' }
}

function normalizeWriteBindingValue(actionId: KeybindingActionId, value: unknown): string[] | null {
  if (value === null) {
    return null
  }
  if (!Array.isArray(value) || !value.every((binding) => typeof binding === 'string')) {
    throw new Error('Use a string array or null.')
  }
  const normalized = normalizeKeybindingArrayForAction(actionId, value)
  if (!Array.isArray(normalized)) {
    throw new Error(normalized.ok ? 'Unable to parse shortcut.' : normalized.error)
  }
  return normalized
}

function parseBindingSection(
  value: unknown,
  section: string,
  diagnostics: KeybindingFileDiagnostic[],
  options: { skipRootKeys?: boolean } = {}
): KeybindingOverrides {
  if (value === undefined) {
    return {}
  }
  if (!isJsonObject(value)) {

View on GitHub (pinned to 1136503c6a)

Solutions

Pass bindings as string[] (e.g. ['Cmd+K']) or null to clear.
If you have a single string, wrap it: [binding] before calling write.
Validate Array.isArray(v) && v.every(x => typeof x === 'string') before the write.

Example fix

// before
writeKeybindingOverride(path, platform, actionId, 'Cmd+K')
// after
writeKeybindingOverride(path, platform, actionId, ['Cmd+K'])

Defensive patterns

Strategy: validation

Validate before calling

function isValidWriteBindings(v: unknown): v is string[] | null {
  return v === null || (Array.isArray(v) && v.every((b) => typeof b === 'string'))
}
if (!isValidWriteBindings(value)) throw new Error('pass string[] or null')

Type guard

function isStringArrayOrNull(v: unknown): v is string[] | null {
  return v === null || (Array.isArray(v) && v.every((b) => typeof b === 'string'))
}

Try / catch

try { writeKeybindingOverride(path, platform, actionId, bindings) }
catch (e) { if (/string array or null/.test(String((e as Error).message))) notifyInvalidBinding(); else throw e }

Prevention

Always pass string[] (or null to clear) to the write API.
Wrap single strings in an array before writing.
Validate array-of-string before feeding parsed JSON into writes.

When it happens

Trigger: writeKeybindingOverride is called with a non-null non-array value (number, object, boolean, or an array containing non-strings like numbers/null). Typical when a programmatic caller reuses the looser read schema for a write.

Common situations: Settings migration code feeding parsed JSON values directly into the write API. A custom UI control emitting a single string instead of ['cmd+k']. JSON config hand-edited to a non-array.

Related errors

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/071977ed462d5738. Report an issue: GitHub.