Exceptions

All custom exceptions raised by Streamlit Lightweight Charts Pro.

Exception Hierarchy

StreamlitLightweightChartsProError (base)
├── ConfigurationError
│   ├── ComponentNotAvailableError
│   └── InvalidConfigurationError
├── ValidationError
│   ├── InvalidDataError
│   ├── InvalidColorError
│   ├── InvalidSeriesTypeError
│   └── InvalidCoordinateError
└── DataProcessingError
    ├── SerializationError
    └── DataTransformError

Exception Classes

Custom exception classes for the Streamlit Lightweight Charts Pro library.

This module defines custom exception classes specific to the Streamlit wrapper while also re-exporting core exceptions from the lightweight_charts_pro package. The exception hierarchy provides clear, specific error messages for various validation and configuration issues that may occur during chart creation.

Exception Hierarchy:

ValidationError (base) ├── TypeValidationError │ ├── DataItemsTypeError │ ├── AnnotationItemsTypeError (Streamlit-specific) │ ├── SeriesItemsTypeError (Streamlit-specific) │ ├── PriceScaleIdTypeError (Streamlit-specific) │ ├── PriceScaleOptionsTypeError (Streamlit-specific) │ ├── InstanceTypeError (Streamlit-specific) │ ├── TypeMismatchError (Streamlit-specific) │ └── TrendDirectionIntegerError (Streamlit-specific) ├── ValueValidationError │ ├── ColorValidationError │ ├── TimeValidationError │ ├── RangeValidationError │ └── ExitTimeAfterEntryTimeError (Streamlit-specific) ├── RequiredFieldError ├── DataFrameValidationError └── BaseValueFormatError (Streamlit-specific) ConfigurationError (base) ├── ComponentNotAvailableError (Streamlit-specific) ├── NpmNotFoundError (Streamlit-specific) └── CliNotFoundError (Streamlit-specific)

Usage Example:

```python from streamlit_lightweight_charts_pro.exceptions import (

ComponentNotAvailableError, ValidationError,

)

try:: # Component creation logic if not component_available:

raise ComponentNotAvailableError()
except ComponentNotAvailableError as e:: st.error(str(e))

```

For more information, see the lightweight_charts_pro.exceptions module.

exception streamlit_lightweight_charts_pro.exceptions.AnnotationItemsTypeError[source]

Bases: TypeValidationError

Raised when annotation items are not of the correct Annotation type.

This exception is thrown when attempting to add annotations to a chart but the provided items are not instances of the Annotation class. All annotation items must be valid Annotation objects.

Example

```python # This will raise AnnotationItemsTypeError chart.add_annotations([“not”, “annotations”])

# Correct usage chart.add_annotations([create_text_annotation(…)]) ```

__init__()[source]

Initialize AnnotationItemsTypeError with standard type error message.

Parameters:: None
Raises:: None –

exception streamlit_lightweight_charts_pro.exceptions.BaseValueFormatError[source]

Bases: ValidationError

Raised when a baseline chart base value has invalid format.

Baseline charts require a base value dict with specific ‘type’ and ‘price’ keys. This exception is raised when the base value doesn’t match this required format.

Example

```python # This will raise BaseValueFormatError base_value = {“price”: 100} # Missing ‘type’ key

# Correct usage base_value = {“type”: 0, “price”: 100} ```

__init__()[source]

Initialize BaseValueFormatError with format requirements message.

Parameters:: None
Raises:: None –

exception streamlit_lightweight_charts_pro.exceptions.CliNotFoundError[source]

Bases: ConfigurationError

Raised when the CLI command is not found in the system PATH.

This exception occurs when attempting to run CLI commands but the streamlit-lightweight-charts-pro CLI is not available in the system PATH. This typically indicates an installation issue.

Example

```python import shutil

if not shutil.which(“streamlit-lightweight-charts-pro”):: raise CliNotFoundError()

```

__init__()[source]

Initialize CliNotFoundError with installation check guidance.

Parameters:: None
Raises:: None –

exception streamlit_lightweight_charts_pro.exceptions.ColorValidationError[source]

Bases: ValidationError

Raised when color format is invalid.

This exception is used when a color value doesn’t match expected formats (hex or rgba).

Parameters:

property_name (str) – Name of the property with invalid color.
color_value (str) – The invalid color value.

Example

>>> raise ColorValidationError("backgroundColor", "invalid")
# Error: Invalid color format for backgroundColor: 'invalid'.
# Must be hex or rgba.

__init__(property_name, color_value)[source]

Initialize ColorValidationError.

Parameters:

property_name (str) – Property name containing the color.
color_value (str) – The invalid color value.

exception streamlit_lightweight_charts_pro.exceptions.ColumnMappingRequiredError[source]

Bases: RequiredFieldError

Raised when column mapping is required but not provided.

This exception is used when DataFrame or Series data is provided without the necessary column mapping configuration.

Example

>>> raise ColumnMappingRequiredError()
# Error: column_mapping is required when providing DataFrame or
# Series data is required

__init__()[source]: Initialize ColumnMappingRequiredError with standard message.

exception streamlit_lightweight_charts_pro.exceptions.ComponentNotAvailableError[source]

Bases: ConfigurationError

Raised when the Streamlit component function is not available.

This exception occurs when the component fails to initialize properly, typically due to missing frontend assets or incorrect installation. It extends ConfigurationError to indicate a setup/configuration issue.

message

A descriptive error message with troubleshooting guidance.

Type:: str

Example

```python if not component_func:

raise ComponentNotAvailableError()

```

__init__()[source]

Initialize ComponentNotAvailableError with a descriptive message.

Parameters:: None
Raises:: None –

exception streamlit_lightweight_charts_pro.exceptions.ConfigurationError[source]

Bases: Exception

Base exception for configuration-related errors.

This exception is raised when there are issues with system configuration, environment setup, or package initialization.

Parameters:: message (str) – Descriptive error message explaining the configuration issue.

Example

>>> raise ConfigurationError("Invalid configuration detected")

__init__(message)[source]

Initialize ConfigurationError with a message.

Parameters:: message (str) – Error message describing the configuration issue.

exception streamlit_lightweight_charts_pro.exceptions.DataFrameValidationError[source]

Bases: ValidationError

Raised when DataFrame validation fails.

This exception provides helper methods for common DataFrame validation errors like missing columns or invalid data types.

Example

>>> error = DataFrameValidationError.missing_column("price")
>>> raise error
# Error: DataFrame is missing required column: price

classmethod invalid_data_type(data_type)[source]

Create error for invalid data type.

Parameters:: data_type (type) – The invalid data type provided.
Returns:: Configured error instance.
Return type:: DataFrameValidationError

Example

>>> error = DataFrameValidationError.invalid_data_type(str)
>>> raise error

classmethod missing_column(column)[source]

Create error for missing DataFrame column.

Parameters:: column (str) – Name of the missing column.
Returns:: Configured error instance.
Return type:: DataFrameValidationError

Example

>>> error = DataFrameValidationError.missing_column("time")
>>> raise error

classmethod missing_columns_mapping(missing_columns, required, mapping)[source]

Create error for missing columns in mapping.

Parameters:

missing_columns (list[str]) – List of missing column names.
required (list[str]) – List of required column names.
mapping (dict[str, str]) – The column mapping that was provided.

Returns:

Configured error instance.

Return type:

DataFrameValidationError

Example

>>> error = DataFrameValidationError.missing_columns_mapping(
...     ["price"], ["time", "price"], {"time": "timestamp"}
... )
>>> raise error

exception streamlit_lightweight_charts_pro.exceptions.DataItemsTypeError[source]

Bases: TypeValidationError

Raised when data items are not correct type.

This exception indicates that items in a data list are not instances of Data class or its subclasses.

Example

>>> raise DataItemsTypeError()
# Error: All items in data list must be instances of Data or its
# subclasses

__init__()[source]: Initialize DataItemsTypeError with standard message.

exception streamlit_lightweight_charts_pro.exceptions.DuplicateError[source]

Bases: ValidationError

Raised when duplicate values are detected.

This exception is used when a unique constraint is violated, such as duplicate IDs, names, or other identifiers.

Parameters:

field_name (str) – Name of the field where duplicate was detected.
value (Any) – The duplicate value.

Example

>>> raise DuplicateError("series_id", "main")
# Error: Duplicate series_id: main

__init__(field_name, value)[source]

Initialize DuplicateError.

Parameters:

field_name (str) – Field name where duplicate was found.
value (Any) – The duplicate value.

exception streamlit_lightweight_charts_pro.exceptions.ExitTimeAfterEntryTimeError[source]

Bases: ValueValidationError

Raised when a trade’s exit time is not after its entry time.

In trade visualization, the exit time must chronologically follow the entry time. This exception is raised when this constraint is violated, which would result in an invalid or confusing trade representation.

Example

```python # This will raise ExitTimeAfterEntryTimeError trade = TradeData(

entry_time=”2024-01-02”, exit_time=”2024-01-01”, # Before entry! …

)

# Correct usage trade = TradeData(

entry_time=”2024-01-01”, exit_time=”2024-01-02”, …

__init__()[source]

Initialize ExitTimeAfterEntryTimeError with a descriptive message.

Parameters:: None
Raises:: None –

exception streamlit_lightweight_charts_pro.exceptions.InstanceTypeError[source]

Bases: TypeValidationError

Raised when a value must be an instance of a specific type.

This is a general-purpose type validation exception for checking that values are instances of expected classes. Optionally allows None values when allow_none is True.

attr_name

Name of the attribute being validated.

Type:: str

value_type

The expected type for the value.

Type:: type

allow_none

Whether None is an acceptable value.

Type:: bool

Example

```python if not isinstance(value, ChartOptions):

raise InstanceTypeError(“options”, ChartOptions, allow_none=True)

```

__init__(attr_name, value_type, allow_none=False)[source]

Initialize InstanceTypeError with attribute name and expected type.

Parameters:

attr_name (str) – The name of the attribute being validated.
value_type (type) – The type that the value should be an instance of.
allow_none (bool, optional) – If True, None is also an acceptable value. Defaults to False.

Raises:

None –

exception streamlit_lightweight_charts_pro.exceptions.InvalidMarkerPositionError[source]

Bases: ValidationError

Raised when marker position is invalid.

Parameters:

position (str) – The invalid position value.
marker_type (str) – The type of marker.

Example

>>> raise InvalidMarkerPositionError("top", "circle")
# Error: Invalid position 'top' for marker type circle

__init__(position, marker_type)[source]

Initialize InvalidMarkerPositionError.

Parameters:

position (str) – The invalid position string.
marker_type (str) – Type of marker being configured.

exception streamlit_lightweight_charts_pro.exceptions.NotFoundError[source]

Bases: ValidationError

Raised when a requested resource is not found.

Parameters:

resource_type (str) – Type of resource (e.g., “Series”, “Chart”).
identifier (str) – Identifier used to search for the resource.

Example

>>> raise NotFoundError("Series", "main-series")
# Error: Series with identifier 'main-series' not found

__init__(resource_type, identifier)[source]

Initialize NotFoundError.

Parameters:

resource_type (str) – Type of the missing resource.
identifier (str) – Identifier that was searched for.

exception streamlit_lightweight_charts_pro.exceptions.NpmNotFoundError[source]

Bases: ConfigurationError

Raised when NPM is not found in the system PATH.

Building the frontend assets requires Node.js and NPM to be installed. This exception is raised when attempting to build frontend assets but NPM cannot be found in the system PATH.

Example

```python import shutil

if not shutil.which(“npm”):: raise NpmNotFoundError()

```

__init__()[source]

Initialize NpmNotFoundError with installation guidance.

Parameters:: None
Raises:: None –

exception streamlit_lightweight_charts_pro.exceptions.PriceScaleIdTypeError[source]

Bases: TypeValidationError

Raised when a price scale ID is not a string.

Price scale IDs must be string values to properly identify and reference different price scales in multi-series charts. This exception is raised when a non-string value is provided as a price scale identifier.

scale_name

The name of the scale that has the invalid ID.

Type:: str

actual_type

The actual type that was provided.

Type:: type

Example

```python # This will raise PriceScaleIdTypeError series.price_scale_id = 123

# Correct usage series.price_scale_id = “right” ```

__init__(scale_name, actual_type)[source]

Initialize PriceScaleIdTypeError with scale name and actual type.

Parameters:

scale_name (str) – The name of the price scale with the invalid ID.
actual_type (type) – The type that was incorrectly provided instead of a string.

Raises:

None –

exception streamlit_lightweight_charts_pro.exceptions.PriceScaleOptionsTypeError[source]

Bases: TypeValidationError

Raised when price scale options are not a PriceScaleOptions object.

Price scale configuration must be provided as a PriceScaleOptions instance. This exception is raised when an invalid type is provided for price scale options, such as a dict or other object type.

scale_name

The name of the scale with invalid options.

Type:: str

actual_type

The actual type that was provided.

Type:: type

Example

```python # This will raise PriceScaleOptionsTypeError series.price_scale_options = {“mode”: 0}

# Correct usage series.price_scale_options = PriceScaleOptions(mode=PriceScaleMode.NORMAL) ```

__init__(scale_name, actual_type)[source]

Initialize PriceScaleOptionsTypeError with scale name and type info.

Parameters:

scale_name (str) – The name of the price scale with invalid options.
actual_type (type) – The type that was incorrectly provided instead of PriceScaleOptions.

Raises:

None –

exception streamlit_lightweight_charts_pro.exceptions.RangeValidationError[source]

Bases: ValueValidationError

Raised when value is outside valid range.

This exception is used for numeric range validation, supporting minimum-only, maximum-only, or bounded ranges.

Parameters:

field_name (str) – Name of the field being validated.
value (float | int) – The value that failed validation.
min_value (Optional[float]) – Minimum acceptable value, if any.
max_value (Optional[float]) – Maximum acceptable value, if any.

Example

>>> raise RangeValidationError("opacity", 1.5, 0.0, 1.0)
# Error: opacity must be between 0.0 and 1.0, got 1.5

__init__(field_name, value, min_value=None, max_value=None)[source]

Initialize RangeValidationError.

Parameters:

field_name (str) – Name of the field being validated.
value (float | int) – Invalid value provided.
min_value (Optional[float]) – Minimum bound, if applicable.
max_value (Optional[float]) – Maximum bound, if applicable.

exception streamlit_lightweight_charts_pro.exceptions.RequiredFieldError[source]

Bases: ValidationError

Raised when a required field is missing.

This exception indicates that a mandatory field was not provided when creating or updating an object.

Parameters:: field_name (str) – Name of the required field that is missing.

Example

>>> raise RequiredFieldError("title")
# Error: title is required

__init__(field_name)[source]

Initialize RequiredFieldError.

Parameters:: field_name (str) – Name of the missing required field.

exception streamlit_lightweight_charts_pro.exceptions.SeriesItemsTypeError[source]

Bases: TypeValidationError

Raised when series items are not of the correct Series type.

This exception occurs when trying to add series to a chart but the provided items are not valid Series instances. All series must inherit from the base Series class (e.g., LineSeries, CandlestickSeries).

Example

```python # This will raise SeriesItemsTypeError chart.add_series([{“data”: data}])

# Correct usage chart.add_series([LineSeries(data)]) ```

__init__()[source]

Initialize SeriesItemsTypeError with standard type error message.

Parameters:: None
Raises:: None –

exception streamlit_lightweight_charts_pro.exceptions.TimeValidationError[source]

Bases: ValidationError

Raised when time validation fails.

This exception is used for time-related validation errors such as invalid time strings or unsupported time types.

Parameters:: message (str) – Description of the time validation failure.

Example

>>> raise TimeValidationError("Invalid timestamp format")
# Error: Time validation failed: Invalid timestamp format

__init__(message)[source]

Initialize TimeValidationError.

Parameters:: message (str) – Time validation failure description.

classmethod invalid_time_string(time_value)[source]

Create error for invalid time string.

Parameters:: time_value (str) – The invalid time string.
Returns:: Configured error instance.
Return type:: TimeValidationError

Example

>>> error = TimeValidationError.invalid_time_string("not-a-date")
>>> raise error

classmethod unsupported_type(time_type)[source]

Create error for unsupported time type.

Parameters:: time_type (type) – The unsupported type.
Returns:: Configured error instance.
Return type:: TimeValidationError

Example

>>> error = TimeValidationError.unsupported_type(list)
>>> raise error

exception streamlit_lightweight_charts_pro.exceptions.TrendDirectionIntegerError[source]

Bases: TypeValidationError

Raised when a trend direction value is not an integer.

Trend direction indicators must be integer values (typically -1, 0, or 1) to represent bearish, neutral, or bullish trends. This exception is raised when a non-integer value is provided for trend direction.

field_name

Name of the field containing the invalid trend value.

Type:: str

expected_type

Description of the expected type.

Type:: str

actual_type

The actual type that was provided.

Type:: str

Example

```python # This will raise TrendDirectionIntegerError data.trend_direction = “up”

# Correct usage data.trend_direction = 1 # Bullish ```

__init__(field_name, expected_type, actual_type)[source]

Initialize TrendDirectionIntegerError with field and type details.

Parameters:

field_name (str) – The name of the field being validated.
expected_type (str) – A description of the expected type (e.g., “an integer”).
actual_type (str) – The name or description of the actual type provided.

Raises:

None –

exception streamlit_lightweight_charts_pro.exceptions.TypeMismatchError[source]

Bases: TypeValidationError

Raised when there is a type mismatch between expected and actual types.

This exception is used for strict type checking where the actual type does not match the expected type. Unlike InstanceTypeError, this checks for exact type matches rather than instance relationships.

attr_name

Name of the attribute with mismatched type.

Type:: str

value_type

The expected type.

Type:: type

actual_type

The actual type that was provided.

Type:: type

Example

```python if type(value) != int:

raise TypeMismatchError(“count”, int, type(value))

```

__init__(attr_name, value_type, actual_type)[source]

Initialize TypeMismatchError with expected and actual type info.

Parameters:

attr_name (str) – The name of the attribute being validated.
value_type (type) – The type that was expected.
actual_type (type) – The actual type that was provided.

Raises:

None –

exception streamlit_lightweight_charts_pro.exceptions.TypeValidationError[source]

Bases: ValidationError

Raised when type validation fails.

This exception is used when a value is of an incorrect type. It provides formatted error messages that clearly indicate what type was expected versus what was received.

Parameters:

field_name (str) – Name of the field that failed validation.
expected_type (str) – Description of the expected type.
actual_type (Optional[str]) – Description of the actual type received. If None, only expected type is shown.

Example

>>> raise TypeValidationError("price", "float", "str")
# Error: price must be float, got str

__init__(field_name, expected_type, actual_type=None)[source]

Initialize TypeValidationError.

Parameters:

field_name (str) – Name of the field being validated.
expected_type (str) – Expected type description.
actual_type (Optional[str]) – Actual type received, if known.

exception streamlit_lightweight_charts_pro.exceptions.UnsupportedTimeTypeError[source]

Bases: TypeValidationError

Raised when time type is unsupported.

Parameters:: time_type (type) – The unsupported time type.

Example

>>> raise UnsupportedTimeTypeError(list)
# Error: time unsupported type, got list

__init__(time_type)[source]

Initialize UnsupportedTimeTypeError.

Parameters:: time_type (type) – The unsupported type provided.

exception streamlit_lightweight_charts_pro.exceptions.ValidationError[source]

Bases: Exception

Base exception for all validation errors.

This is the root exception class for all validation-related errors in the package. It should be caught when you want to handle any type of validation failure.

Parameters:: message (str) – Descriptive error message explaining the validation failure.

Example

>>> raise ValidationError("Invalid input provided")

__init__(message)[source]

Initialize ValidationError with a message.

Parameters:: message (str) – Error message describing the validation failure.

exception streamlit_lightweight_charts_pro.exceptions.ValueValidationError[source]

Bases: ValidationError

Raised when value validation fails.

This class provides helper methods for common validation patterns, reducing the need for overly specific exception classes. It handles validations like positive numbers, ranges, and required fields.

Parameters:

field_name (str) – Name of the field that failed validation.
message (str) – Description of why validation failed.

Example

>>> error = ValueValidationError.positive_value("price", -10)
>>> raise error
# Error: price must be positive, got -10

__init__(field_name, message)[source]

Initialize ValueValidationError.

Parameters:

field_name (str) – Name of the field being validated.
message (str) – Validation failure description.

classmethod in_range(field_name, min_val, max_val, value)[source]

Create error for out-of-range value.

Helper method for validating that a value falls within a specified range [min_val, max_val].

Parameters:

field_name (str) – Name of the field being validated.
min_val (float) – Minimum acceptable value (inclusive).
max_val (float) – Maximum acceptable value (inclusive).
value (float | int) – The invalid value that was provided.

Returns:

Configured error instance.

Return type:

ValueValidationError

Example

>>> error = ValueValidationError.in_range("percentage", 0, 100, 150)
>>> raise error

classmethod non_negative_value(field_name, value=None)[source]

Create error for negative value.

Helper method for validating that a value is non-negative (>= 0).

Parameters:

field_name (str) – Name of the field being validated.
value (float | int | None) – The invalid value that was provided. If None, only shows constraint without value.

Returns:

Configured error instance.

Return type:

ValueValidationError

Example

>>> error = ValueValidationError.non_negative_value("count", -1)
>>> raise error

classmethod positive_value(field_name, value)[source]

Create error for non-positive value.

Helper method for validating that a value is positive (> 0).

Parameters:

field_name (str) – Name of the field being validated.
value (float | int) – The invalid value that was provided.

Returns:

Configured error instance.

Return type:

ValueValidationError

Example

>>> error = ValueValidationError.positive_value("price", -5)
>>> raise error

classmethod required_field(field_name)[source]

Create error for missing required field.

Helper method for validating that a required field is present.

Parameters:: field_name (str) – Name of the required field.
Returns:: Configured error instance.
Return type:: ValueValidationError

Example

>>> error = ValueValidationError.required_field("title")
>>> raise error

Usage Examples

Catching specific exceptions:

from streamlit_lightweight_charts_pro import renderChart
from streamlit_lightweight_charts_pro.exceptions import (
    InvalidDataError,
    InvalidColorError
)

try:
    renderChart(data, lineColor="invalid-color")
except InvalidColorError as e:
    st.error(f"Invalid color: {e}")
except InvalidDataError as e:
    st.error(f"Data error: {e}")

Catching all package exceptions:

from streamlit_lightweight_charts_pro.exceptions import (
    StreamlitLightweightChartsProError
)

try:
    renderChart(data)
except StreamlitLightweightChartsProError as e:
    st.error(f"Chart error: {e}")