stablyai/orca · error · Error

Failed to save quick command

Error message

Failed to save quick command

What it means

Thrown inside the persist queue when `settings.updateTerminalQuickCommands` returns ok:false. The host's error.message is preferred; the literal is the fallback. (A sibling throw at line 204 covers the case where the success payload fails to parse - same message.) The queue rolls back optimistic state for the failed mutation.

Source

Thrown at mobile/src/session/use-quick-commands.ts:196

        id: mutationContext.nextMutationId + 1,
        mutation: commandMutation
      }
      mutationContext.nextMutationId = mutation.id
      mutationContext.pending.push(mutation)
      const optimistic = applyTerminalQuickCommandMutation(commandsRef.current, commandMutation)
      commandsRef.current = optimistic
      setCommands(optimistic)
      setError(null)

      const send = async (): Promise<boolean> => {
        let succeeded = false
        let failureMessage: string | null = null
        try {
          const response = await client.sendRequest('settings.updateTerminalQuickCommands', {
            mutation: commandMutation
          })
          if (!response.ok) {
            throw new Error(
              (response as RpcFailure).error.message || 'Failed to save quick command'
            )
          }
          const confirmed = readQuickCommands((response as RpcSuccess).result)
          if (!confirmed) {
            // Why: treating an invalid success payload as [] would let the next
            // full-list mutation erase commands that still exist on the host.
            throw new Error('Failed to save quick command')
          }
          mutationContext.confirmed = confirmed
          succeeded = true
          return true
        } catch (err) {
          failureMessage = err instanceof Error ? err.message : 'Failed to save quick command'
          return false
        } finally {
          mutationContext.pending = mutationContext.pending.filter(
            (pending) => pending.id !== mutation.id

View on GitHub (pinned to 1136503c6a)

Solutions

1. Retry the edit after reconnecting.
2. Reload quick commands (settings.getTerminalQuickCommands) to resync.
3. Check host settings store.
4. Avoid mutating during reconnect.

Example fix

// before
if (!response.ok) {
  throw new Error((response as RpcFailure).error.message || 'Failed to save quick command')
}
// after
if (!response.ok) {
  throw new RpcMethodError('settings.updateTerminalQuickCommands', response.error)
}

if (!client || connState !== 'connected') {
  setError('Waiting for desktop...')
  return false
}

function isRpcFailure(r: RpcResponse): r is RpcFailure {
  return r.ok === false
}

const ok = await persist(mutation)
if (!ok) setError('Failed to save quick command - retry')

When it happens

Trigger: Host rejects the quick-command mutation - settings store write failure, schema validation, transport error, or relay cutover. Optimistic UI was already applied and will be rolled back to the last confirmed list.

Common situations: Editing/adding/deleting a quick command during a reconnect window; host settings file locked; mutation payload references a command id the host does not know; relay cutover mid-save.

Related errors

• ${RPC error message}
• response.error.message
• Unable to read markdown
• Waiting for desktop...
• Failed to save review notes

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