Error Messages Reference

This page catalogues all exception types used in CTSolvers, with live examples and recommended fixes. CTSolvers uses enriched exceptions from CTBase.Exceptions that carry structured fields (got, expected, suggestion, context) for actionable error messages.

Exception Types

CTSolvers uses three exception types from CTBase.Exceptions:

All three accept keyword arguments for structured messages:

using CTSolvers
using CTBase: CTBase
const Exceptions = CTBase.Exceptions

NotImplemented — Contract Not Implemented

Thrown when a concrete type doesn't implement a required contract method.

Strategy contract — missing id

abstract type IncompleteStrategy <: CTBase.Strategies.AbstractStrategy end

julia> CTBase.Strategies.id(IncompleteStrategy)ERROR: NotImplemented
│
│  Strategy ID method not implemented
│
│  Method   id(::Type{<:Main.IncompleteStrategy})
│
│  Context  AbstractStrategy.id - required method implementation
│  Hint     Implement id(::Type{<:Main.IncompleteStrategy}) to return a unique Symbol identifier
└─

Fix: Implement the missing method:

CTBase.Strategies.id(::Type{<:IncompleteStrategy}) = :my_strategy

Strategy contract — missing metadata

julia> CTBase.Strategies.metadata(IncompleteStrategy)ERROR: NotImplemented
│
│  Strategy metadata method not implemented
│
│  Method   metadata(::Type{<:Main.IncompleteStrategy})
│
│  Context  AbstractStrategy.metadata - required method implementation
│  Hint     Implement metadata(::Type{<:Main.IncompleteStrategy}) to return StrategyMetadata with OptionDefinitions
└─

Optimization problem contract — missing builder

struct MinimalProblem <: CTSolvers.Optimization.AbstractOptimizationProblem end

julia> CTSolvers.Optimization.get_adnlp_model_builder(MinimalProblem())ERROR: NotImplemented
│
│  ADNLP model builder not implemented
│
│  Method   get_adnlp_model_builder(prob::Main.MinimalProblem)
│
│  Context  AbstractOptimizationProblem.get_adnlp_model_builder - required method implementation
│  Hint     Implement get_adnlp_model_builder for Main.MinimalProblem to support ADNLPModels backend
└─

julia> CTSolvers.Optimization.get_exa_model_builder(MinimalProblem())ERROR: NotImplemented
│
│  ExaModel builder not implemented
│
│  Method   get_exa_model_builder(prob::Main.MinimalProblem)
│
│  Context  AbstractOptimizationProblem.get_exa_model_builder - required method implementation
│  Hint     Implement get_exa_model_builder for Main.MinimalProblem to support ExaModels backend
└─

Where it's thrown

IncorrectArgument — Invalid Arguments

Thrown for invalid values, types, or routing errors. This is the most common exception in CTSolvers.

Type mismatch in extraction

When extract_option receives a value of the wrong type:

julia> def = CTBase.Options.OptionDefinition(
           name = :max_iter, type = Integer, default = 100,
           description = "Maximum iterations",
       )max_iter::Integer (default: 100)
julia> CTBase.Options.extract_option((max_iter = "hello",), def)ERROR: IncorrectArgument
│
│  Invalid option type
│
│  Got       value hello of type String
│  Expected  Integer
│
│  Context   Option extraction for max_iter
│  Hint      Ensure the option value matches the expected type
└─

Fix: Provide a value of the correct type.

Validator failure

When a value doesn't satisfy the validator constraint:

bad_def = CTBase.Options.OptionDefinition(
    name = :tol, type = Real, default = 1e-8,
    description = "Tolerance",
    validator = x -> x > 0 || throw(Exceptions.IncorrectArgument(
        "Invalid tolerance value",
        got = "tol=$x",
        expected = "positive real number (> 0)",
        suggestion = "Provide a positive tolerance value (e.g., 1e-6, 1e-8)",
        context = "tol validation",
    )),
)

julia> CTBase.Options.extract_option((tol = -1.0,), bad_def)ERROR: IncorrectArgument
│
│  Invalid tolerance value
│
│  Got       tol=-1.0
│  Expected  positive real number (> 0)
│
│  Context   tol validation
│  Hint      Provide a positive tolerance value (e.g., 1e-6, 1e-8)
└─

Fix: Provide a value that satisfies the validator constraint.

Type mismatch in OptionDefinition constructor

When the default value doesn't match the declared type:

julia> CTBase.Options.OptionDefinition(
           name = :count, type = Integer, default = "hello",
           description = "A count",
       )ERROR: IncorrectArgument
│
│  Type mismatch in option definition
│
│  Got       default value hello of type String
│  Expected  value of type Integer
│
│  Context   OptionDefinition constructor - validating type compatibility
│  Hint      Ensure the default value matches the declared type, or adjust the type parameter
└─

Fix: Ensure the default value matches the declared type.

Invalid OptionValue source

julia> CTBase.Options.OptionValue(42, :invalid_source)ERROR: IncorrectArgument
│
│  Invalid option source
│
│  Got       source=invalid_source
│  Expected  :default, :user, or :computed
│
│  Context   OptionValue constructor - validating source provenance
│  Hint      Use one of the valid source symbols: :default (tool default), :user (user-provided), or :computed (derived)
└─

Fix: Use :default, :user, or :computed.

ExtensionError — Extension Not Loaded

Thrown when a solver requires a package extension that hasn't been loaded.

julia> CTSolvers.Solvers.Ipopt()ERROR: ExtensionError
│
│  missing dependencies to create Ipopt, access options, and solve problems
│
│  Missing  NLPModelsIpopt
│
│  Context  Load NLPModelsIpopt extension first: using NLPModelsIpopt
│  Hint     Run: using NLPModelsIpopt
└─

Fix: Load the required package before using the solver:

using NLPModelsIpopt  # loads the CTSolversIpopt extension
solver = Solvers.Ipopt(max_iter = 1000)

Where it's thrown

Display Examples

OptionDefinition display

CTBase.Options.OptionDefinition(
    name = :max_iter, type = Integer, default = 1000,
    description = "Maximum number of iterations",
    aliases = (:maxiter,),
)

max_iter (maxiter)::Integer (default: 1000)

OptionValue display

CTBase.Options.OptionValue(1000, :user)

1000 (user)

CTBase.Options.OptionValue(1e-8, :default)

1.0e-8 (default)

NotProvided display

CTBase.Options.NotProvided

NotProvided

Option extraction — successful

def = CTBase.Options.OptionDefinition(
    name = :grid_size, type = Int, default = 100,
    description = "Grid size", aliases = (:n,),
)
opt_value, remaining = CTBase.Options.extract_option((n = 200, tol = 1e-6), def)
println("Extracted: ", opt_value)
println("Remaining: ", remaining)

Extracted: 200 (user)
Remaining: (tol = 1.0e-6,)

Multiple option extraction

defs = [
    CTBase.Options.OptionDefinition(
        name = :grid_size, type = Int, default = 100, description = "Grid size",
    ),
    CTBase.Options.OptionDefinition(
        name = :tol, type = Float64, default = 1e-6, description = "Tolerance",
    ),
]
extracted, remaining = CTBase.Options.extract_options((grid_size = 200, max_iter = 1000), defs)
println("Extracted: ", extracted)
println("Remaining: ", remaining)

Extracted: Dict{Symbol, CTBase.Options.OptionValue}(:grid_size => 200 (user), :tol => 1.0e-6 (default))
Remaining: (max_iter = 1000,)

Best Practices for Error Messages

When implementing new validators or error paths, follow the CTSolvers convention:

throw(Exceptions.IncorrectArgument(
    "Short, clear description of the problem",
    got        = "what the user actually provided",
    expected   = "what was expected instead",
    suggestion = "actionable fix the user can apply",
    context    = "ModuleName.function_name - specific validation step",
))

• got: Show the actual value, including its type if relevant
• expected: Be specific about valid values or ranges
• suggestion: Provide a concrete example the user can copy
• context: Include the module and function name for traceability