Error Handling

Copy Markdown View Source

SDK operations return %CursorCliSdk.Error{} for normalized failures.

case CursorCliSdk.run("Hello") do
  {:ok, text} ->
    text

  {:error, %CursorCliSdk.Error{kind: :auth_error} = error} ->
    raise error.message
end

Error Fields

FieldMeaning
:kindStable normalized error atom
:messageHuman-readable summary
:causeOriginal exception or runtime failure
:detailsStderr or additional diagnostic text
:contextMap of command/runtime context
:exit_codeCLI exit code when known

Common Kinds

  • :auth_error
  • :cli_not_found
  • :config_invalid
  • :input_error
  • :parse_error
  • :stream_start_failed
  • :stream_timeout
  • :transport_error
  • :transport_exit
  • :user_cancelled

Stream Errors

execute/2 emits %CursorCliSdk.Types.ErrorEvent{} instead of raising. Fatal stream errors stop the enumerable.

Command Errors

Command helpers such as CursorCliSdk.Command.models/1 and CursorCliSdk.MCP.list/1 return {:error, %CursorCliSdk.Error{}} when the CLI exits non-zero or cannot be launched.