---
title: "Guide: debugging"
description: "smabar plugin reference: Guide: debugging"
canonical: "https://smabar.com/docs/plugin-ref-guide-debugging/"
lang: en
---

# Guide: debugging

> smabar plugin reference: Guide: debugging

Canonical HTML version: https://smabar.com/docs/plugin-ref-guide-debugging/ · Language: en · Publisher: smabar (https://smabar.com)

---

[Build my plugin](https://smabar.com/build-my-plugin.md) · [All references](https://smabar.com/docs/plugin-ref-index.md) · [Install the ZIP](https://smabar.com/docs/install-plugin-zip.md)

Source: smabar 1.5.0, revision `a019f2563965edc37a5e8d84742ea1ff2fa6f824`. [Export metadata and checksums](https://smabar.com/plugin-reference/export.json).

This is an offline reference. MCP calls quoted below describe the connected workflow; use the linked documents and create local files instead. Live state, installed plugins, available providers and the user's active theme are unknown. Never claim a live check.

Read with [styling](https://smabar.com/docs/plugin-ref-styling.md) and [examples](https://smabar.com/docs/plugin-ref-examples.md).

## status

```json
"plugin_list shows every plugin with status starting/running/failed/stopped, the failure reason, its code folder, its data directory, and updateAvailable for a bundled plugin whose replacement is waiting for the user. A python plugin that is starting with a reason is waiting for the managed Python runtime (download or a failed download that smabar retries by itself); a failed reason that ends in 'restarting in …' is a temporary failure the supervisor retries, one that ends in 'giving up until the plugin folder changes' is parked until you fix and save the plugin."
```

## logs

```json
"plugin_logs(id) is the one call that answers \"why did that not work\". It returns TWO lists. pluginEntries carries a source per entry: \"log\" (your app.log calls), \"stdout\" (anything you printed that was not JSON-RPC), \"stderr\" (a Python traceback lands here), \"core\" (smabar ignored malformed optional input or rejected one operation, with the supported alternative), and \"shell\" (see markup below). Repeated identical core diagnostics are written once. coreEntries is what smabar said ABOUT your plugin: it started, it crashed, it is in restart backoff, its manifest is invalid. A plugin that dies before its first line writes nothing at all into pluginEntries, so always read both. Filter with level, contains and limit. plugin_logs WITHOUT an id returns the bar's own log instead, including its UI (target smabar::shell) and its dependencies."
```

## markup

```json
"The sanitizer rewrites your HTML and REMOVES what it does not allow — a <script>, an onclick=, an unsupported src. Unknown sb-* classes are kept but have no kit rule. Inline spacing and type, icon-only controls without a name, raw locale keys and overlong KPI values are flagged as well. Each case is reported into your own log as a \"shell\" entry naming the problem and the supported alternative, once per distinct problem per surface; a clean render re-arms it, so a problem that comes back is reported again. The write reply summarises them under reload.warnings. If markup is missing or unstyled, look for that entry FIRST."
```

## data

```json
"plugin_data(id) lists what you actually wrote into app.data_dir, and with a path returns one file's content. Use it to check whether your cache exists and holds what you think. Binary files (a SQLite database among them) come back as metadata only — use plugin_commands/plugin_call for structured queries where supported."
```

## commonFailures

```json
[
  "\"smabar.json was NOT written: entry file … does not exist\" — the manifest came before the entry script; write the siblings, then smabar.json.",
  "\"tile is not declared in smabar.json\" — app.render used an id the manifest does not list.",
  "Plugin stuck in `starting` — a first python run resolving dependencies through uv; wait and poll plugin_list.",
  "Tile stays empty — nothing was rendered yet. Render from @app.on_ready, which runs once right after initialize.",
  "Tile renders but an element is missing — the sanitizer removed it; the \"shell\" entry in plugin_logs says which and why.",
  "Text shows raw keys like \"clock.title\" — t() ran before initialize; move that render into @app.on_ready.",
  "\"ModuleNotFoundError: No module named 'views'\" as reload.error — a sibling module was never written; plugin_write_file every file of the plugin, then smabar.json again.",
  "Tile is missing although the plugin runs — the user hid it: plugin_list shows it under hiddenTiles; plugin_set_visible(\"plugin:<id>:<tile>\", true) brings it back."
]
```