Exceptions and warnings

Errors and warnings raised by skforecast_ai. All of them are importable from the package root, for example from skforecast_ai import LLMCallError.

Every error derives from SkforecastAIError, which carries a code from a closed set, the argument at fault in field (None when the error is not tied to one) and an optional remedy in hint, which is not part of str(exc). A program can react to code and field without parsing the message. The errors for invalid inputs also derive from the built-in exception raised before 0.4.0 (ValueError, TypeError or FileNotFoundError), so existing except clauses keep catching them with the same message.

Name	Raised or warned by	When
SkforecastAIError	every method	Base class of the errors below. Catch it to handle any error of skforecast-ai.
InvalidInputError	every method	An argument, or the plan, profile or CV passed in, is not valid. A ValueError.
InvalidInputTypeError	every method	An argument has a type that is not accepted, such as a bool test_size or a compare() candidate config that is not a dict, or a CVResult is unpacked as a tuple. A TypeError, and also an InvalidInputError and therefore a ValueError.
DataContentError	forecast(), backtest(), compare() and the CLI	Every argument is valid and the content of the data, or of the future exogenous variables, cannot be used for what was asked: a missing value of the target that a prediction or a metric reads, final rows without a target value, or future exogenous variables whose columns, dates or values do not fit the data and the plan. An InvalidInputError and therefore a ValueError, with the same code and field.
DataNotFoundError	every method that takes data, and the CLI	The CSV path does not exist or the URL cannot be read, or a JSON or CSV input of the CLI does not exist. A FileNotFoundError.
LLMRequiredError	ask(), refine_plan() and create_cv() with a prompt	The method needs an LLM and none was configured at init time.
LLMCallError	ask()	The call to the LLM fails. There is no deterministic answer to fall back on, so the provider error is raised (chained as original_error) instead of returned as text.
ForecastExecutionError	forecast(), backtest()	The generated script does not compile or fails while running. The script and the full traceback are available as generated_code and execution_traceback, and the line and the statement that failed as failed_line and failed_statement.
AllCandidatesFailedError	compare()	Every candidate configuration fails, so there is no leaderboard to return. The per-candidate reasons are in failures.
CandidateFailedWarning	compare()	One candidate fails; the comparison continues with the rest and the failure is recorded in ComparisonResult.failures.
MissingBackendWarning	compare() without candidates	The backend of the default foundation model (chronos-forecasting for Chronos-2) is not installed, so ForecasterFoundation is left out of the comparison instead of failing. Install it with pip install skforecast-ai[foundation].
DataSentToLLMWarning	ask()	A result with values of its own (predictions, metrics) is sent to the LLM while send_data_to_llm=False. Pass send_data_to_llm=True to acknowledge it.
PlanEditsDiscardedWarning	refine_plan()	The plan holds values edited by hand (a key of forecaster_kwargs, the preprocessing steps) that the refined plan does not keep. The warning names them and its text is kept in the warnings of the refined plan. The ones refine_plan() takes as overrides (forecaster, lags, metric...) can be passed again; the others cannot be kept.
UnrecommendedForecasterWarning	plan()	The requested forecaster is supported but was not among the profile's candidates for this dataset (for example, Auto-ARIMA on high-frequency data).

refine_plan() and create_cv() do not raise when the LLM fails: they emit a UserWarning and return their deterministic result, which is valid on its own.

The warnings that skforecast emits while forecast(), backtest() and compare() run the generated script (for example MissingValuesWarning) are shown when the script ends, after its printed output is discarded. Your warning filters apply as usual: warnings.simplefilter('ignore', category=...) hides them, and an error filter makes the script fail.

Error codes

code	Raised as	When
invalid_argument	InvalidInputError, InvalidInputTypeError, DataContentError	An argument or a received object is not valid.
insufficient_data	InvalidInputError	The data is too short for what was asked: fewer than two folds for the cross-validation, lags and window features longer than the data allows, a target column without any value, or a series of ForecasterRecursiveMultiSeries without values or shorter than its lags and window features.
data_not_found	DataNotFoundError	A file to read (the CSV path or URL, or an input of the CLI) cannot be found.
data_unreadable	DataNotFoundError, InvalidInputError	An input exists but cannot be parsed: a CSV file that pandas cannot read (empty, binary, not UTF-8, or rows with more fields than the header), a URL whose content is not a CSV (DataNotFoundError, as before), or the JSON of --from-plan or --from-profile in the CLI.
missing_dependency	InvalidInputError	The package of the chosen estimator, or the backend package of the foundation model, is not installed. Checked before forecast() and backtest() run the script.
execution_failed	ForecastExecutionError	The generated script fails.
all_candidates_failed	AllCandidatesFailedError	Every candidate of compare() fails.
llm_required	LLMRequiredError	The method needs an LLM and none is configured.
llm_call_failed	LLMCallError	The call to the LLM fails.
internal_error		Not raised by skforecast-ai: ErrorInfo uses it for any exception that skforecast-ai did not raise itself (it is also the default code of a bare SkforecastAIError).

Some errors carry a remedy in hint that does not depend on Python, for a program or an agent that passes paths (the CLI prints it as a tip): for example how to write the dates, or what a CSV file that cannot be read must look like. Messages that suggest a pandas call keep it, and hint gives the remedy without it.

ErrorInfo.from_exception(), in skforecast_ai.schemas, turns an exception into plain data (code, message, field, hint) for a reader outside Python: it never holds a traceback or generated code, takes the field of a pydantic ValidationError from the location of its first error, and describes any other exception by its type and the first line of its message.

skforecast_ai.exceptions

Classes:

Name	Description
SkforecastAIError	Base class of the errors raised by skforecast-ai.
InvalidInputError	Raised when an argument, or the plan, profile or CV passed in, is not
InvalidInputTypeError	Raised when an argument has a type that is not accepted.
DataContentError	Raised when the content of the data, or of the future exogenous
DataNotFoundError	Raised when a file to read cannot be found: the data (a CSV path or
LLMRequiredError	Raised when a method that requires an LLM is called without one.
LLMCallError	Raised by ask() when the call to the LLM fails.
ForecastExecutionError	Raised when the generated forecasting code fails to compile or fails
AllCandidatesFailedError	Raised by compare() when every candidate configuration fails.
CandidateFailedWarning	Warned by compare() when an individual candidate fails.
DataSentToLLMWarning	Warned when data values are sent to the LLM against send_data_to_llm.
MissingBackendWarning	Warned by compare() when a foundation model candidate is left out.
PlanEditsDiscardedWarning	Warned by refine_plan() when edits made to the plan are discarded.
UnrecommendedForecasterWarning	Warned by plan() when the requested forecaster is not recommended.

Attributes:

Name	Type	Description
ErrorCode		Closed set of codes carried by SkforecastAIError.code.
ERROR_CODES	tuple[str, ...]

Attributes

ErrorCode module-attribute

ErrorCode = Literal[
    "invalid_argument",
    "insufficient_data",
    "data_not_found",
    "data_unreadable",
    "missing_dependency",
    "execution_failed",
    "all_candidates_failed",
    "llm_required",
    "llm_call_failed",
    "internal_error",
]

Closed set of codes carried by SkforecastAIError.code.

ERROR_CODES module-attribute

ERROR_CODES = get_args(ErrorCode)

Classes

SkforecastAIError

SkforecastAIError(
    message="", *, code=None, field=None, hint=None
)

Bases: Exception

Base class of the errors raised by skforecast-ai.

Every error carries a stable code from a closed set and, when one argument is at fault, its name in field, so a program (an agent, the CLI) can react to the kind of error without parsing the message. The message is the text of the exception; hint is an optional remedy kept out of it, so str(exc) is the message alone.

Each subclass also derives from the built-in exception that was raised before the hierarchy existed (ValueError, TypeError, FileNotFoundError), so existing except clauses keep catching it.

Parameters:

Name	Type	Description	Default
message	str	Error message, returned by str(exc).	''
code	str	One of ERROR_CODES. None uses the default code of the class.	None
field	str	Name of the argument (or the field of a plan, profile or CV) at fault. None when the error is not tied to a single argument.	None
hint	str	Optional remedy, not part of str(exc).	None

Attributes:

Name	Type	Description
code	str	One of ERROR_CODES.
field	(str, None)	Name of the argument at fault.
hint	(str, None)	Optional remedy.

Source code in skforecast_ai/exceptions.py

def __init__(
    self,
    message: str = "",
    *,
    code: ErrorCode | None = None,
    field: str | None = None,
    hint: str | None = None,
) -> None:
    if code is not None and code not in ERROR_CODES:
        raise ValueError(
            f"Unknown error code {code!r}. Valid codes: {list(ERROR_CODES)}."
        )
    super().__init__(message)
    self.code = code if code is not None else self.default_code
    self.field = field
    self.hint = hint

Attributes

default_code class-attribute instance-attribute

default_code = 'internal_error'

code instance-attribute

code = code if code is not None else self.default_code

field instance-attribute

field = field

hint instance-attribute

hint = hint

InvalidInputError

InvalidInputError(
    message="", *, code=None, field=None, hint=None
)

Bases: SkforecastAIError, ValueError

Raised when an argument, or the plan, profile or CV passed in, is not valid.

A subclass of ValueError, the class raised for these errors before skforecast-ai had its own hierarchy. The default code is 'invalid_argument'; errors caused by too little data use 'insufficient_data', and a missing optional package 'missing_dependency'.

Attributes:

Name	Type	Description
default_code	ErrorCode

Source code in skforecast_ai/exceptions.py

def __init__(
    self,
    message: str = "",
    *,
    code: ErrorCode | None = None,
    field: str | None = None,
    hint: str | None = None,
) -> None:
    if code is not None and code not in ERROR_CODES:
        raise ValueError(
            f"Unknown error code {code!r}. Valid codes: {list(ERROR_CODES)}."
        )
    super().__init__(message)
    self.code = code if code is not None else self.default_code
    self.field = field
    self.hint = hint

Attributes

default_code class-attribute instance-attribute

default_code = 'invalid_argument'

InvalidInputTypeError

InvalidInputTypeError(
    message="", *, code=None, field=None, hint=None
)

Bases: InvalidInputError, TypeError

Raised when an argument has a type that is not accepted.

A subclass of TypeError, the class raised for these errors before skforecast-ai had its own hierarchy, and of InvalidInputError, so catching InvalidInputError covers every invalid input.

Source code in skforecast_ai/exceptions.py

def __init__(
    self,
    message: str = "",
    *,
    code: ErrorCode | None = None,
    field: str | None = None,
    hint: str | None = None,
) -> None:
    if code is not None and code not in ERROR_CODES:
        raise ValueError(
            f"Unknown error code {code!r}. Valid codes: {list(ERROR_CODES)}."
        )
    super().__init__(message)
    self.code = code if code is not None else self.default_code
    self.field = field
    self.hint = hint

DataContentError

DataContentError(
    message="", *, code=None, field=None, hint=None
)

Bases: InvalidInputError

Raised when the content of the data, or of the future exogenous variables, cannot be used for what was asked, although every argument is valid: a missing value of the target that a prediction or a metric reads, final rows without a target value, or future exogenous variables whose columns, dates or values do not fit the data and the plan.

A subclass of InvalidInputError, with its code and its field ('data', 'exog' or 'test_size'), so catching InvalidInputError or ValueError still covers it. Catch it to tell a problem of the values, which is solved in the data, from an argument to correct.

Source code in skforecast_ai/exceptions.py

def __init__(
    self,
    message: str = "",
    *,
    code: ErrorCode | None = None,
    field: str | None = None,
    hint: str | None = None,
) -> None:
    if code is not None and code not in ERROR_CODES:
        raise ValueError(
            f"Unknown error code {code!r}. Valid codes: {list(ERROR_CODES)}."
        )
    super().__init__(message)
    self.code = code if code is not None else self.default_code
    self.field = field
    self.hint = hint

DataNotFoundError

DataNotFoundError(
    message="", *, code=None, field=None, hint=None
)

Bases: SkforecastAIError, FileNotFoundError

Raised when a file to read cannot be found: the data (a CSV path or URL), or a JSON or CSV input of the CLI.

A subclass of FileNotFoundError, the class raised for these errors before skforecast-ai had its own hierarchy. The code is 'data_not_found'.

Attributes:

Name	Type	Description
default_code	ErrorCode

Source code in skforecast_ai/exceptions.py

def __init__(
    self,
    message: str = "",
    *,
    code: ErrorCode | None = None,
    field: str | None = None,
    hint: str | None = None,
) -> None:
    if code is not None and code not in ERROR_CODES:
        raise ValueError(
            f"Unknown error code {code!r}. Valid codes: {list(ERROR_CODES)}."
        )
    super().__init__(message)
    self.code = code if code is not None else self.default_code
    self.field = field
    self.hint = hint

Attributes

default_code class-attribute instance-attribute

default_code = 'data_not_found'

LLMRequiredError

LLMRequiredError(method_name)

Bases: SkforecastAIError

Raised when a method that requires an LLM is called without one.

The code is 'llm_required'.

Parameters:

Name	Type	Description	Default
method_name	str	Name of the method that requires an LLM.	required

Attributes:

Name	Type	Description
default_code	ErrorCode

Source code in skforecast_ai/exceptions.py

def __init__(self, method_name: str) -> None:
    super().__init__(
        f"`{method_name}()` requires an LLM. "
        "Pass `llm=...` when creating ForecastingAssistant."
    )

Attributes

default_code class-attribute instance-attribute

default_code = 'llm_required'

LLMCallError

LLMCallError(llm, original_error)

Bases: SkforecastAIError

Raised by ask() when the call to the LLM fails.

ask() has no deterministic answer to fall back on, so a failed call (network, authentication, provider error, or a local model that is not reachable) is reported as an error instead of a result whose explanation is not an answer. The original exception is chained and kept as an attribute. The code is 'llm_call_failed'.

Parameters:

Name	Type	Description	Default
llm	str	LLM provider string in format 'provider:model_name'.	required
original_error	Exception	The exception raised by the provider or the agent.	required

Attributes:

Name	Type	Description
llm	str	LLM provider string in format 'provider:model_name'.
original_error	Exception	The exception raised by the provider or the agent.

Source code in skforecast_ai/exceptions.py

def __init__(self, llm: str, original_error: Exception) -> None:
    self.llm = llm
    self.original_error = original_error

    error_type = type(original_error).__name__
    super().__init__(
        f"The call to the LLM '{llm}' failed.\n\n"
        f"  {error_type}: {original_error}\n\n"
        f"Check the provider, the model name and the credentials, then "
        f"retry. The original exception is available as `original_error`."
    )

Attributes

default_code class-attribute instance-attribute

default_code = 'llm_call_failed'

llm instance-attribute

llm = llm

original_error instance-attribute

original_error = original_error

ForecastExecutionError

ForecastExecutionError(
    original_error,
    generated_code,
    execution_traceback,
    failed_line=None,
    failed_statement=None,
)

Bases: SkforecastAIError

Raised when the generated forecasting code fails to compile or fails during exec().

The short message surfaces the original error. The full generated code and traceback are available as attributes for debugging, together with the line and the statement of the generated code that failed. The code is 'execution_failed'.

Parameters:

Name	Type	Description	Default
original_error	Exception	The exception raised while compiling or executing the code.	required
generated_code	str	The generated Python code that was executed.	required
execution_traceback	str	The full formatted traceback from execution.	required
failed_line	int	Line of generated_code (1-based) where the error was raised. None when it cannot be located. generated_code is the code that ran, without the CSV loading of the script that forecast_code() and backtest_code() return, so the numbering differs from that script.	None
failed_statement	str	Source of the statement of generated_code that failed, all its lines included (only the header of a for, if or with statement, and only the line when the code does not compile). None when it cannot be located.	None

Attributes:

Name	Type	Description
original_error	Exception	The exception raised while compiling or executing the code.
generated_code	str	The generated Python code that was executed.
execution_traceback	str	The full formatted traceback from execution.
failed_line	(int, None)	Line of generated_code (1-based) where the error was raised.
failed_statement	(str, None)	Source of the statement of generated_code that failed.

Source code in skforecast_ai/exceptions.py

def __init__(
    self,
    original_error: Exception,
    generated_code: str,
    execution_traceback: str,
    failed_line: int | None = None,
    failed_statement: str | None = None,
) -> None:
    self.original_error = original_error
    self.generated_code = generated_code
    self.execution_traceback = execution_traceback
    self.failed_line = failed_line
    self.failed_statement = failed_statement

    error_type = type(original_error).__name__
    error_msg = str(original_error)
    message = (
        f"Error executing generated forecasting code.\n\n"
        f"  {error_type}: {error_msg}"
    )
    super().__init__(message)

Attributes

default_code class-attribute instance-attribute

default_code = 'execution_failed'

original_error instance-attribute

original_error = original_error

generated_code instance-attribute

generated_code = generated_code

execution_traceback instance-attribute

execution_traceback = execution_traceback

failed_line instance-attribute

failed_line = failed_line

failed_statement instance-attribute

failed_statement = failed_statement

AllCandidatesFailedError

AllCandidatesFailedError(failures)

Bases: SkforecastAIError

Raised by compare() when every candidate configuration fails.

A comparison with zero successful candidates has no leaderboard and no winner, so it is reported as a failure instead of returning a winner-less result. The code is 'all_candidates_failed'.

Parameters:

Name	Type	Description	Default
failures	dict	Mapping of candidate name to the CandidateFailure describing why it failed, in the order the candidates were evaluated.	required

Attributes:

Name	Type	Description
failures	dict	Mapping of candidate name to its CandidateFailure.

Source code in skforecast_ai/exceptions.py

def __init__(self, failures: dict[str, CandidateFailure]) -> None:
    self.failures = failures

    message = (
        f"{_all_candidates_failed_summary(failures)}\n\n"
        f"Inspect a failure with `exc.failures['<name>'].traceback` or "
        f"`exc.failures['<name>'].generated_code`."
    )
    super().__init__(message)

Attributes

default_code class-attribute instance-attribute

default_code = 'all_candidates_failed'

failures instance-attribute

failures = failures

CandidateFailedWarning

Bases: UserWarning

Warned by compare() when an individual candidate fails.

The comparison continues with the remaining candidates; the failure is recorded in the 'error' column of the results table and a CandidateFailure is kept in ComparisonResult.failures.

DataSentToLLMWarning

Bases: UserWarning

Warned when data values are sent to the LLM against send_data_to_llm.

ask(context=...) always sends the predicted values a result carries, because a question about a result cannot be answered from summary statistics alone. That override is silent otherwise, so a user who set send_data_to_llm=False for privacy reasons would still ship values off the machine without being told. A result that carries no such values (for example a CodeGenerationResult) does not trigger it.

The input data is not sent: a result holds only the model's output, never the data it was fitted on.

MissingBackendWarning

Bases: UserWarning

Warned by compare() when a foundation model candidate is left out.

compare() without candidates includes ForecasterFoundation, whose default model needs a backend package (for Chronos-2, chronos-forecasting) that skforecast-ai does not install by default. When that package is missing, the candidate is dropped instead of failing on every call, and this warning says which package to install. The comparison explanation records it as well.

PlanEditsDiscardedWarning

Bases: UserWarning

Warned by refine_plan() when edits made to the plan are discarded.

refine_plan() builds the refined plan with plan(), from the decisions it carries over (the overrides of RefinePlanOverrides and the fields in ForecastPlan.overridden_fields). A value changed by hand in the plan (in forecaster_kwargs, the metric, the preprocessing steps...) that plan() would not build is therefore lost. The warning names those fields; its text is also kept in the warnings of the refined plan.

UnrecommendedForecasterWarning

Bases: UserWarning

Warned by plan() when the requested forecaster is not recommended.

The forecaster is supported and is used as requested, but it was left out of ForecastingProfile.forecaster_candidates for this dataset, typically because it is expected to be very slow or to perform poorly (for example, Auto-ARIMA on high-frequency data).

skforecast_ai.schemas.errors.ErrorInfo

Bases: BaseModel

Plain-data description of an error, for a reader outside Python.

Built with ErrorInfo.from_exception(). It never holds a traceback or generated code: only a stable code, the message, the argument at fault and an optional remedy.

Attributes:

Name	Type	Description
code	str	One of skforecast_ai.exceptions.ERROR_CODES. 'internal_error' for an exception that skforecast-ai did not raise itself.
message	str	Error message. For an internal error, the exception type and the first line of its message, at most 200 characters.
field	(str, None)	Name of the argument (or the field of a plan, profile or CV) at fault, when the error is tied to one.
hint	(str, None)	Optional remedy.

Methods:

Name	Description
from_exception	Describe an exception raised by a skforecast-ai call.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(frozen=True, extra='forbid')

code instance-attribute

code

message instance-attribute

message

field class-attribute instance-attribute

field = None

hint class-attribute instance-attribute

hint = None

Methods:

from_exception classmethod

from_exception(exc)

Describe an exception raised by a skforecast-ai call.

• A SkforecastAIError keeps its code, message, field and hint. The message of an AllCandidatesFailedError leaves out how to inspect exc.failures, which only exists in Python.
• A pydantic ValidationError (a plan or a profile that does not validate) is 'invalid_argument'. When the validator raised a SkforecastAIError, its code, message and hint are used. The field is the location of the first error, or the field of that error when the location is empty (a check on the whole model). When there are several errors, the message says how many are not shown.
• Any other exception is 'internal_error', described by its type and the first line of its message.

Parameters:

Name	Type	Description	Default
exc	Exception	Exception to describe.	required

Returns:

Name	Type	Description
info	ErrorInfo	Plain-data description of exc.

Source code in skforecast_ai/schemas/errors.py

@classmethod
def from_exception(cls, exc: Exception) -> ErrorInfo:
    """
    Describe an exception raised by a skforecast-ai call.

    - A `SkforecastAIError` keeps its code, message, field and hint.
      The message of an `AllCandidatesFailedError` leaves out how to
      inspect `exc.failures`, which only exists in Python.
    - A pydantic `ValidationError` (a plan or a profile that does not
      validate) is `'invalid_argument'`. When the validator raised a
      `SkforecastAIError`, its code, message and hint are used. The
      field is the location of the first error, or the field of that
      error when the location is empty (a check on the whole model).
      When there are several errors, the message says how many are
      not shown.
    - Any other exception is `'internal_error'`, described by its type
      and the first line of its message.

    Parameters
    ----------
    exc : Exception
        Exception to describe.

    Returns
    -------
    info : ErrorInfo
        Plain-data description of `exc`.
    """

    if isinstance(exc, ValidationError):
        return cls._from_validation_error(exc)
    if isinstance(exc, AllCandidatesFailedError):
        return cls(
            code    = exc.code,
            message = _all_candidates_failed_summary(exc.failures),
            field   = exc.field,
            hint    = exc.hint,
        )
    if isinstance(exc, SkforecastAIError):
        return cls(
            code    = exc.code,
            message = str(exc),
            field   = exc.field,
            hint    = exc.hint,
        )

    return cls(
        code    = "internal_error",
        message = _one_line_summary(
                      error_type = type(exc).__name__,
                      message    = str(exc),
                      max_length = _INTERNAL_MESSAGE_MAX_LENGTH,
                  ),
    )