slint-ui/slint · error · AttributeError

Callback '{name}' cannot be used with a callback decorator f

Error message

Callback '{name}' cannot be used with a callback decorator for an async function, as it is not declared in Slint component

What it means

The component-level (non-global) variant of the async callback validation: when a subclass method decorated with @slint.callback is async and has no global_name, cls_init calls compdef.callback_returns_void(name); a None return means the component itself declares no callback with that name, and this AttributeError is raised at instantiation.

Source

Thrown at api/python/slint/slint/__init__.py:188

                is_async = getattr(value, "slint.async", False)
                if is_async:
                    if "global_name" in callback_info:
                        global_name = callback_info["global_name"]
                        is_void = compdef.global_callback_returns_void(
                            global_name, name
                        )
                        if is_void is None:
                            raise AttributeError(
                                f"Callback '{name}' in global '{global_name}' cannot be used with a callback decorator for an async function, as it is not declared in Slint component"
                            )
                        if not is_void:
                            raise RuntimeError(
                                f"Callback '{name}' in global '{global_name}' cannot be used with a callback decorator for an async function, as it doesn't return void"
                            )
                    else:
                        is_void = compdef.callback_returns_void(name)
                        if is_void is None:
                            raise AttributeError(
                                f"Callback '{name}' cannot be used with a callback decorator for an async function, as it is not declared in Slint component"
                            )
                        if not is_void:
                            raise RuntimeError(
                                f"Callback '{name}' cannot be used with a callback decorator for an async function, as it doesn't return void"
                            )

                def mk_callback(
                    self: Any, callback: typing.Callable[..., Any]
                ) -> typing.Callable[..., Any]:
                    def invoke(*args: Any, **kwargs: Any) -> Any:
                        return callback(self, *args, **kwargs)

                    return invoke

                if "global_name" in callback_info:
                    self.__instance__.set_global_callback(
                        callback_info["global_name"], name, mk_callback(self, value)

View on GitHub (pinned to a9ea814a58)

Solutions

Declare the callback on the component in .slint: `component App { callback quit(); ... }`.
Match the Python method name to the Slint name (underscores for dashes).
Re-run slint.load_file() after editing the .slint file before creating instances.
Remove @slint.callback from methods that are not invoked by Slint.

Example fix

# before (main.slint)
export component App { callback clicked(); }

@slint.callback
async def quitted(self): ...  # 'quitted' not declared -> AttributeError

# after
export component App {
    callback clicked();
    callback quitted();
}

Defensive patterns

Strategy: try-catch

Validate before calling

# Before instantiating, assert every component-level async @slint.callback is declared
instance_probe = slint.load_file("app.slint")
comp = getattr(instance_probe, "App")
# instantiate the base class once to reach the definition
probe = comp()
declared = {c.replace("-", "_") for c in probe.__instance__.definition.callbacks}
for name in my_async_callback_names:
    assert name in declared, f"callback '{name}' not declared in .slint"

Try / catch

try:
    app = App()
except AttributeError as e:
    raise SystemExit(f"Undeclared callback: {e}. Declare `callback <name>(...)` on the component and reload via slint.load_file.") from e

Prevention

Re-run slint.load_file after every .slint edit before creating subclass instances.
Use the exact callback name (underscores for dashes) on decorated methods.
Never decorate non-callback helper methods with @slint.callback.

When it happens

Trigger: `@slint.callback` + `async def` on a subclass method whose name is not a `callback ...;` declared directly on the root component in the .slint file — typo, rename drift, dash/underscore mismatch, or a non-callback helper that got decorated.

Common situations: Callback renamed in .slint without updating Python; stale loaded .slint after edits; decorator accidentally applied to an internal method; forgetting that `handle-click` becomes `handle_click` in Python.

Related errors

AI-assisted analysis of slint-ui/slint@a9ea814a58 (2026-08-16). Data as JSON: /api/errors/31ee9de677726d4c. Report an issue: GitHub.