Errors

Every exception the framework raises inherits from BootstackError, so a single except BootstackError catches anything bootstack throws while letting ordinary Python errors propagate. The individual subclasses let you catch one specific failure when you want to handle it precisely.

from bootstack.errors import BootstackError

import bootstack as bs

try:
    risky_setup()
except BootstackError as err:
    # any framework error — log it and fall back
    log.warning("bootstack rejected the setup: %s", err)

The errors

UnknownEventError

Raised by widget.on(name, ...) when name isn’t an event the widget supports — almost always a typo. The message lists the widget and the bad name. Prefer the typed on_*() shorthands (on_click, on_change), which can’t be misspelled; reach for the string form only for dynamic event names:

from bootstack.errors import UnknownEventError

try:
    widget.on(event_name, handler)
except UnknownEventError as err:
    print("no such event:", err)

ParentResolutionError

Raised when a widget can’t find a container to attach to — typically because it was created outside any with container block, or under a parent that isn’t a layout container. The fix is structural: create the widget inside an App or a layout container (Column, Row, Card, …):

with bs.App() as app:
    with bs.Column():
        bs.Label("Inside a container — fine.")

bs.Label("Created with no container")   # ParentResolutionError

DuplicateIdError

Raised by a data source when two records share an id — on load() of rows with a colliding id, or on insert() of a record whose id already exists. Ids identify rows for selection and events, so they must be unique. It is also raised if a source is asked to auto-assign an id but the existing ids aren’t integers:

from bootstack.data import MemoryDataSource
from bootstack.errors import DuplicateIdError

ds = MemoryDataSource().load([{"id": 1, "name": "Ada"}])

try:
    ds.insert({"id": 1, "name": "Linus"})   # 1 already exists
except DuplicateIdError as err:
    print("id clash:", err)

SerializationError

Raised when a JSON-backed store is handed a value it can’t persist. A Store and the SQLite/file-backed data sources keep their values as JSON, so values must be JSON-serializable (scalars, lists, dicts). To carry a live Python object, use an in-memory source instead:

from bootstack.store import Store
from bootstack.errors import SerializationError

store = Store("settings")

try:
    store.set("connection", open("db.sqlite"))   # not JSON-serializable
except SerializationError as err:
    print("can't persist that:", err)

InvalidChoiceError

Raised at construction when an argument that names a behavior mode is given a value outside its documented set. These arguments — selection_mode, sorting_mode, scrollbars and their siblings — are read by comparing against one value, so a near-miss spelling used to select the other behavior silently. The message lists the values that are accepted:

from bootstack.errors import InvalidChoiceError

with bs.App() as app:
    try:
        bs.DataTable(rows=rows, selection_mode="multiple")   # it's 'multi'
    except InvalidChoiceError as err:
        print(err)   # ... Valid values: 'none', 'single', 'multi'.

This one is also a built-in ValueError, so except ValueError catches it as well.

NavigationError

Raised by the navigation containers — PageStack and Tabs, and the AppShell side navigation — when a key is wrong: adding a page, tab, or workspace whose key already exists, or selecting, looking up, or removing one whose key doesn’t exist:

from bootstack.errors import NavigationError

with bs.App() as app:
    tabs = bs.Tabs()
    tabs.add("home", label="Home")

    try:
        tabs.add("home", label="Duplicate")   # key already exists
    except NavigationError as err:
        print("nav:", err)

ThemeError

Raised when a theme operation fails — most often requesting a theme name that isn’t registered, or loading a malformed theme definition:

from bootstack.errors import ThemeError

try:
    bs.set_theme("not-a-real-theme")
except ThemeError as err:
    print("bad theme:", err)

StyleBuilderError

Raised when a widget style can’t be built — typically an unsupported variant for that widget type:

from bootstack.errors import StyleBuilderError

try:
    bs.Button("Go", variant="not-a-variant")
except StyleBuilderError as err:
    print("bad variant:", err)

API reference

The complete reference for every exception type lives in Errors. At a glance:

BootstackError	Base class for all public API errors.
DuplicateIdError	Raised when a data source receives a record whose id already exists.
InvalidChoiceError	Raised when a keyword argument is given a value outside its valid set.
NavigationError	Raised when a navigation operation references a wrong key.
ParentResolutionError	Raised when a widget cannot resolve its parent.
SerializationError	Raised when a file-backed store or data source receives a value it cannot persist.
StyleBuilderError	Raised when a widget style cannot be built.
ThemeError	Raised when a theme-related operation fails.
UnknownEventError	Raised by widget.on(name, ...) when name cannot be resolved.