Conjure.Error exception (Conjure v0.1.1-alpha)

Error types for Conjure operations.

Provides structured errors with context for debugging and error handling. All Conjure errors include a type, message, and optional details map.

Error Types

:skill_not_found - Skill with given name not found in registry
:invalid_frontmatter - SKILL.md frontmatter is malformed or missing required fields
:invalid_skill_structure - Skill directory structure is invalid
:file_not_found - Requested file does not exist
:permission_denied - Access to path is not allowed
:execution_failed - Tool execution failed
:execution_timeout - Tool execution timed out
:docker_unavailable - Docker is not available or not running
:container_error - Container operation failed
:max_iterations_reached - Conversation loop exceeded maximum iterations

Anthropic Skills API Errors

:anthropic_api_error - Anthropic API returned an error response
:skills_limit_exceeded - More than 8 skills specified (API limit)
:skill_upload_failed - Failed to upload skill to Anthropic
:pause_turn_max_exceeded - Too many pause_turn iterations
:container_not_found - Container ID is invalid or expired
:file_download_failed - Failed to download file from Files API
:invalid_skill_spec - Invalid skill specification tuple

Native Execution Errors

:not_a_native_skill - Module does not implement NativeSkill behaviour
:native_callback_missing - Required callback not implemented
:native_execution_failed - Native skill callback returned an error

Storage Errors

:storage_init_failed - Storage backend initialization failed
:storage_cleanup_failed - Storage cleanup failed
:storage_write_failed - Writing to storage failed
:storage_read_failed - Reading from storage failed

Example

case Conjure.load_skill("/invalid/path") do
  {:ok, skill} -> skill
  {:error, %Conjure.Error{type: :file_not_found} = error} ->
    Logger.warning("Skill not found: #{error.message}")
end

Summary

Types

error_type()

t()

Functions

anthropic_api_error(status, message, details \\ %{})

Creates an Anthropic API error.

container_error(operation, reason)

Creates a container error.

container_not_found(container_id)

Creates a container not found error.

docker_unavailable(reason)

Creates a Docker unavailable error.

execution_failed(command, exit_code, output)

Creates an execution failed error.

execution_timeout(command, timeout_ms)

Creates an execution timeout error.

file_download_failed(file_id, reason)

Creates a file download failed error.

file_not_found(path)

Creates a file not found error.

invalid_frontmatter(path, reason)

Creates an invalid frontmatter error.

invalid_skill_spec(spec)

Creates an invalid skill spec error.

invalid_skill_structure(path, reason)

Creates an invalid skill structure error.

max_iterations_reached(max)

Creates a max iterations reached error.

missing_api_callback(message)

Creates a missing API callback error.

native_callback_missing(module, callback)

Creates a native callback missing error.

native_execution_failed(module, callback, reason)

Creates a native execution failed error.

not_a_native_skill(module)

Creates a not a native skill error.

path_not_allowed(path, allowed_paths)

Creates a path not allowed error.

pause_turn_max_exceeded(iterations, max)

Creates a pause_turn max exceeded error.

permission_denied(path)

Creates a permission denied error.

skill_not_found(name)

Creates a skill not found error.

skill_upload_failed(path, reason)

Creates a skill upload failed error.

skills_limit_exceeded(count, max)

Creates a skills limit exceeded error.

storage_cleanup_failed(reason)

Creates a storage cleanup failed error.

storage_init_failed(reason)

Creates a storage initialization failed error.

storage_read_failed(path, reason)

Creates a storage read failed error.

storage_write_failed(path, reason)

Creates a storage write failed error.

wrap(error)

Wraps a raw error into a Conjure.Error.

zip_error(path, reason)

Creates a ZIP error.

Types

error_type()

@type error_type() ::
  :skill_not_found
  | :invalid_frontmatter
  | :invalid_skill_structure
  | :file_not_found
  | :permission_denied
  | :path_not_allowed
  | :execution_failed
  | :execution_timeout
  | :docker_unavailable
  | :container_error
  | :api_error
  | :max_iterations_reached
  | :zip_error
  | :anthropic_api_error
  | :skills_limit_exceeded
  | :skill_upload_failed
  | :pause_turn_max_exceeded
  | :container_not_found
  | :file_download_failed
  | :invalid_skill_spec
  | :not_a_native_skill
  | :native_callback_missing
  | :native_execution_failed
  | :storage_init_failed
  | :storage_cleanup_failed
  | :storage_write_failed
  | :storage_read_failed
  | :unknown

t()

@type t() :: %Conjure.Error{
  __exception__: true,
  details: map(),
  message: String.t(),
  type: error_type()
}

Functions

anthropic_api_error(status, message, details \\ %{})

@spec anthropic_api_error(integer(), String.t(), map()) :: t()

Creates an Anthropic API error.

Used when the Anthropic API returns an error response.

container_error(operation, reason)

@spec container_error(String.t(), term()) :: t()

Creates a container error.

container_not_found(container_id)

@spec container_not_found(String.t()) :: t()

Creates a container not found error.

docker_unavailable(reason)

@spec docker_unavailable(String.t()) :: t()

Creates a Docker unavailable error.

execution_failed(command, exit_code, output)

@spec execution_failed(String.t(), integer(), String.t()) :: t()

Creates an execution failed error.

execution_timeout(command, timeout_ms)

@spec execution_timeout(String.t(), pos_integer()) :: t()

Creates an execution timeout error.

file_download_failed(file_id, reason)

@spec file_download_failed(String.t(), term()) :: t()

Creates a file download failed error.

file_not_found(path)

@spec file_not_found(Path.t()) :: t()

Creates a file not found error.

invalid_frontmatter(path, reason)

@spec invalid_frontmatter(Path.t(), term()) :: t()

Creates an invalid frontmatter error.

invalid_skill_spec(spec)

@spec invalid_skill_spec(term()) :: t()

Creates an invalid skill spec error.

invalid_skill_structure(path, reason)

@spec invalid_skill_structure(Path.t(), String.t()) :: t()

Creates an invalid skill structure error.

max_iterations_reached(max)

@spec max_iterations_reached(pos_integer()) :: t()

Creates a max iterations reached error.

missing_api_callback(message)

@spec missing_api_callback(String.t()) :: t()

Creates a missing API callback error.

Returned when an API callback is required but not provided.

native_callback_missing(module, callback)

@spec native_callback_missing(module(), atom()) :: t()

Creates a native callback missing error.

Returned when a required callback is not implemented by the skill module.

native_execution_failed(module, callback, reason)

@spec native_execution_failed(module(), atom(), term()) :: t()

Creates a native execution failed error.

Returned when a native skill callback returns an error.

not_a_native_skill(module)

@spec not_a_native_skill(module()) :: t()

Creates a not a native skill error.

Returned when a module does not implement the NativeSkill behaviour.

path_not_allowed(path, allowed_paths)

@spec path_not_allowed(Path.t(), [Path.t()]) :: t()

Creates a path not allowed error.

pause_turn_max_exceeded(iterations, max)

@spec pause_turn_max_exceeded(pos_integer(), pos_integer()) :: t()

Creates a pause_turn max exceeded error.

Returned when the conversation loop exceeds maximum pause_turn iterations.

permission_denied(path)

@spec permission_denied(Path.t()) :: t()

Creates a permission denied error.

skill_not_found(name)

@spec skill_not_found(String.t()) :: t()

Creates a skill not found error.

skill_upload_failed(path, reason)

@spec skill_upload_failed(Path.t(), term()) :: t()

Creates a skill upload failed error.

skills_limit_exceeded(count, max)

@spec skills_limit_exceeded(pos_integer(), pos_integer()) :: t()

Creates a skills limit exceeded error.

Anthropic Skills API supports a maximum of 8 skills per request.

storage_cleanup_failed(reason)

@spec storage_cleanup_failed(term()) :: t()

Creates a storage cleanup failed error.

Returned when storage cleanup fails.

storage_init_failed(reason)

@spec storage_init_failed(term()) :: t()

Creates a storage initialization failed error.

Returned when storage backend initialization fails.

storage_read_failed(path, reason)

@spec storage_read_failed(String.t(), term()) :: t()

Creates a storage read failed error.

Returned when reading from storage fails.

storage_write_failed(path, reason)

@spec storage_write_failed(String.t(), term()) :: t()

Creates a storage write failed error.

Returned when writing to storage fails.

wrap(error)

@spec wrap(term()) :: t()

Wraps a raw error into a Conjure.Error.

zip_error(path, reason)

@spec zip_error(Path.t(), term()) :: t()

Creates a ZIP error.