core
API
Generated with
core/org.llm4s/org.llm4s.error

org.llm4s.error

package org.llm4s.error

Members list

Type members

Classlikes

final case class APIError extends LLMError, RecoverableError

API errors for external service calls

API errors for external service calls

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object APIError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
APIError.type
sealed abstract class AssistantError extends Product, Serializable

Assistant-specific error types with rich context and formatting

Assistant-specific error types with rich context and formatting

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Known subtypes
class DisplayError
class EOFError
class FileError
class IOError
class SessionError
Show all
object AssistantError

Attributes

Companion
class
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class AuthenticationError extends LLMError, NonRecoverableError

Raised when the LLM provider rejects the request due to authentication failures.

Raised when the LLM provider rejects the request due to authentication failures.

This is a NonRecoverableError: it cannot be fixed by retrying. The user must provide valid credentials (e.g., API key, token) to resolve this error. Examples include invalid API keys, expired tokens, or unauthorized access to a model.

Value parameters

code

optional error code returned by the provider (e.g., "401", "INVALID_KEY")

message

human-readable description of the authentication failure

provider

the name of the LLM provider (e.g., "openai", "anthropic")

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object AuthenticationError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class ConfigurationError extends LLMError, NonRecoverableError

Raised when there is an issue with the client or operation configuration.

Raised when there is an issue with the client or operation configuration.

This is a NonRecoverableError: it indicates a permanent failure due to missing or invalid configuration values (e.g., missing base URL, invalid model name). The user must correct the configuration to resolve this error.

Value parameters

message

human-readable description of the configuration error

missingKeys

list of configuration keys that were missing or invalid

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ConfigurationError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class ContextError extends LLMError, NonRecoverableError

Context management related errors for token windows and conversation handling

Context management related errors for token windows and conversation handling

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ContextError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
object ErrorRecovery

Advanced pattern matching for error recovery and intelligent retry logic.

Advanced pattern matching for error recovery and intelligent retry logic.

Uses Scala's powerful pattern matching to implement sophisticated error handling strategies with type-safe recovery patterns.

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
final case class ExecutionError(message: String, operation: String, exitCode: Option[Int], cause: Option[Throwable], context: Map[String, String]) extends LLMError, RecoverableError

Execution errors that might succeed on retry.

Execution errors that might succeed on retry.

Represents errors from command or process execution that may be transient, such as temporary resource unavailability or intermittent failures. As a RecoverableError, retry strategies can be applied.

Value parameters

cause

Optional underlying exception

context

Additional key-value context for debugging

exitCode

Optional process exit code if applicable

message

Human-readable error description

operation

The operation that failed (e.g., "bash-script", "api-call")

Attributes

Example 
val error = ExecutionError("Command failed", "bash-script")
 .withExitCode(1)
 .withContext("command", "npm install")
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class InvalidInputError extends LLMError, NonRecoverableError

Error for invalid input values that fail validation.

Error for invalid input values that fail validation.

Provides detailed context about which field was invalid, what value was provided, and why it was rejected. As a NonRecoverableError, the input must be corrected before retrying.

Value parameters

field

The name of the field that has invalid input

message

Human-readable error description

reason

Explanation of why the value is invalid

value

The invalid value that was provided

Attributes

Example 
val error = InvalidInputError("temperature", "2.5", "must be between 0 and 1")
error.context  // Map("field" -> "temperature", "value" -> "2.5", "reason" -> "...")
Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object InvalidInputError

Factory methods for creating InvalidInputError instances.

Factory methods for creating InvalidInputError instances.

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
trait LLMError extends Product, Serializable

Enhanced comprehensive error hierarchy for LLM operations using ADTs.

Enhanced comprehensive error hierarchy for LLM operations using ADTs.

This replaces the simple org.llm4s.llmconnect.model.LLMError with a much more comprehensive error system.

Key improvements over legacy version:

  • Structured context information
  • Recovery guidance built-in - Trait-based recoverability
  • Provider-agnostic design
  • Rich error formatting
  • Type-safe error handling
  • Private case class constructors with smart constructors

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Known subtypes
class APIError
class ContextError
class NetworkError
class SimpleError
class UnknownError
class ServiceError
class SystemError
class TimeoutError
class RerankError
trait AudioIOError
class SaveFailed
trait WavError
trait STTError
class InvalidInput
trait TTSError
Show all
object LLMError

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
LLMError.type
final case class NetworkError extends LLMError, RecoverableError

Raised when a network-level failure occurs during communication with the LLM provider.

Raised when a network-level failure occurs during communication with the LLM provider.

This is a RecoverableError: it indicates transient failures such as connection drops, DNS resolution failures, or temporary unreachability. Retrying the operation may succeed.

Value parameters

cause

optional underlying exception that caused the failure (e.g., java.net.ConnectException)

endpoint

the URL or endpoint that was being accessed

message

human-readable description of the network failure

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object NetworkError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
trait NonRecoverableError extends LLMError

Marker trait for errors that cannot be recovered through retries.

Marker trait for errors that cannot be recovered through retries.

Errors extending this trait indicate permanent failures that require user intervention or code changes to resolve. Examples include authentication failures, invalid input, and configuration errors.

Use pattern matching or LLMError.isRecoverable to check recoverability:

error match {
 case _: RecoverableError => // Apply retry logic
 case _: NonRecoverableError => // Report failure to user
}

Attributes

See also

RecoverableError for errors that may succeed on retry

Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Known subtypes
class ContextError
class SimpleError
class UnknownError
Show all
final case class NotFoundError(message: String, key: String) extends LLMError, NonRecoverableError

Error indicating a required configuration or environment value was not found.

Error indicating a required configuration or environment value was not found.

Use this error when a required configuration key, environment variable, or resource is missing. As a NonRecoverableError, the operation cannot proceed without providing the missing value.

Value parameters

key

The configuration key or identifier that was not found

message

Human-readable error description

Attributes

Example 
val error = NotFoundError("API key not found", "OPENAI_API_KEY")
error.context  // Map("key" -> "OPENAI_API_KEY")
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class OptimisticLockFailure(message: String, memoryId: String, attemptedVersion: Long) extends LLMError, RecoverableError

Error indicating a concurrent modification was detected during an optimistic update.

Error indicating a concurrent modification was detected during an optimistic update.

Returned when an update is attempted but the record has been modified by another concurrent writer since it was last read. Callers should re-read the record and retry the operation.

Value parameters

attemptedVersion

The version number that was expected but not found

memoryId

The ID of the memory record that was concurrently modified

message

Human-readable error description

Attributes

Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ProcessingError extends LLMError, NonRecoverableError

Raised when an internal processing operation fails, such as image or audio processing.

Raised when an internal processing operation fails, such as image or audio processing.

This is a NonRecoverableError: it indicates a failure in processing multimodal inputs (e.g., resampling audio, converting image formats) before sending them to the provider. This usually requires fixing the input media or addressing the underlying cause.

Value parameters

cause

optional underlying exception that caused the processing to fail

message

human-readable description of the processing failure

operation

the specific processing operation that failed (e.g., "audio-resample")

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ProcessingError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class RateLimitError extends LLMError, RecoverableError

Raised when the LLM provider rejects the request due to rate limiting.

Raised when the LLM provider rejects the request due to rate limiting.

This is a RecoverableError: it is safe to retry after waiting. The client can handle this automatically when configured with a retry policy. It provides intelligent retry delays, utilizing provider hints when available.

Value parameters

message

human-readable description of the rate limit

provider

the name of the LLM provider (e.g., "openai", "anthropic")

requestsRemaining

optional number of requests remaining in the current window

resetTime

optional timestamp (in milliseconds) when the rate limit will reset

retryAfter

optional delay hint in seconds from the provider (e.g., from Retry-After header)

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object RateLimitError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
trait RecoverableError extends LLMError

Marker trait for errors that may succeed on retry.

Marker trait for errors that may succeed on retry.

Errors extending this trait indicate transient failures where retrying the operation with appropriate backoff strategies may succeed. Examples include rate limiting, network timeouts, and temporary service unavailability.

Use pattern matching or LLMError.isRecoverable to check recoverability:

error match {
 case _: RecoverableError => // Apply retry logic
 case _: NonRecoverableError => // Report failure
}

Attributes

See also

NonRecoverableError for errors that cannot be recovered

ErrorRecovery for retry utilities

Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Known subtypes
class APIError
class NetworkError
class ServiceError
class SystemError
class TimeoutError
Show all
final case class ServiceError extends LLMError, RecoverableError

Service-level errors from LLM providers

Service-level errors from LLM providers

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ServiceError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class SimpleError extends LLMError, NonRecoverableError

A simple error with just a message and no additional context.

A simple error with just a message and no additional context.

Use this error type for basic error cases where no structured context is needed. For errors with more context, prefer specific error types like ValidationError or ConfigurationError.

Value parameters

message

Human-readable error description

Attributes

Example 
val error = SimpleError("Something went wrong")
error.message  // "Something went wrong"
error.context  // Map.empty
Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object SimpleError

Factory methods for creating SimpleError instances.

Factory methods for creating SimpleError instances.

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class SystemError extends LLMError, RecoverableError

System-level errors for unexpected exceptions that may be transient.

System-level errors for unexpected exceptions that may be transient.

Represents unexpected system failures such as resource exhaustion, temporary unavailability, or other transient issues. As a RecoverableError, these can be retried with appropriate backoff strategies.

Value parameters

cause

Optional underlying exception

message

Human-readable error description

Attributes

Example 
val error = SystemError("Unexpected memory allocation failure", Some(cause))
error.context  // Map("exceptionType" -> "OutOfMemoryError")
Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object SystemError

Factory methods for creating SystemError instances.

Factory methods for creating SystemError instances.

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
object ThrowableOps

Extension methods for converting Throwable to domain-specific LLMError types.

Extension methods for converting Throwable to domain-specific LLMError types.

Provides a uniform way to convert exceptions into the LLM4S error hierarchy, enabling consistent error handling across the codebase.

Attributes

Example 
import org.llm4s.error.ThrowableOps._
val error = new java.net.SocketTimeoutException("timeout").toLLMError
// Returns NetworkError("Request timeout", ...)
// With custom mapper
implicit val mapper: ErrorMapper = customMapper
val customError = exception.toLLMError
Supertypes
class Object
trait Matchable
class Any
Self type
final case class TimeoutError(message: String, timeoutDuration: Duration, operation: String, cause: Option[Throwable], context: Map[String, String]) extends LLMError, RecoverableError

Raised when an operation exceeds its specified time limit.

Raised when an operation exceeds its specified time limit.

Represents operations that timed out. As a RecoverableError, these can potentially succeed with a different timeout, or by retrying with exponential backoff strategies, assuming the service was temporarily slow.

Value parameters

cause

optional underlying exception

context

additional key-value context for debugging

message

human-readable error description

operation

the operation that timed out (e.g., "api-call", "completion")

timeoutDuration

the timeout duration that was exceeded

Attributes

Example 
import scala.concurrent.duration._
val error = TimeoutError("Request timed out", 30.seconds, "api-call")
 .withContext("endpoint", "https://api.openai.com")
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class TokenizerError extends LLMError, NonRecoverableError

Tokenizer-related errors for context management

Tokenizer-related errors for context management

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object TokenizerError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class UnknownError extends LLMError, NonRecoverableError

Unknown/unexpected errors with full exception context

Unknown/unexpected errors with full exception context

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object UnknownError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class ValidationError extends LLMError, NonRecoverableError

Raised when the request parameters or inputs fail validation before being sent to the provider.

Raised when the request parameters or inputs fail validation before being sent to the provider.

This is a NonRecoverableError: it indicates malformed requests, such as providing invalid parameters, missing required fields, or exceeding token limits in the input. The user must fix the request payload to resolve this error.

Value parameters

field

the name of the field that failed validation

message

human-readable description of the validation failure

violations

list of specific validation rules that were violated

Attributes

Companion
object
Supertypes
trait LLMError
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ValidationError

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
Generated with