[BUG] Dashboard screenshot tool not working

[Morrismanski]

💬 What Happened?

📋 Bug Description

ha_config_get_dashboard(include_screenshot=True) blijft "Screenshot requested but dashboard screenshot mode is disabled" rapporteren, ook nadat enable_beta_features én enable_dashboard_screenshot beide bevestigd true staan (via /api/settings/features, origin "file"), de Puppet screenshot-engine draait en bereikbaar is, en dashboard_screenshot_engine_url correct is ingesteld en bevestigd opgeslagen (origin "file") in /api/settings/advanced. Probleem persisteert na meerdere add-on restarts en zelfs na het starten van een volledig nieuwe MCP-sessie/gesprek.

🔄 Steps to Reproduce

1. Add-on installatie van ha-mcp (versie 7.8.1) naast de "Puppet" screenshot-add-on (balloob/home-assistant-addons, slug 0f1cc410_puppet, versie 2.5.0, status started)
2. In de ha-mcp web-settings UI: zet master toggle "Enable beta features" aan
3. Zet sub-toggle "Enable dashboard screenshot mode (beta)" aan
4. Klik "Save advanced settings", klik daarna "Restart"
5. Stel dashboard_screenshot_engine_url in op http://0f1cc410-puppet:10000 via POST /api/settings/advanced (bevestigd opgeslagen, origin: "file", restart_required: true)
6. Restart de add-on (zowel via de web-UI als via ha_manage_addon(action="restart"))
7. Roep ha_config_get_dashboard(url_path="<dashboard>", include_screenshot=True) aan

✅ Expected vs ❌ Actual Behavior

Expected:
Een gerenderde PNG van het dashboard wordt teruggegeven, of een foutmelding die wijst op een daadwerkelijk verbindingsprobleem met de Puppet-engine (bijv. timeout, auth-fout), niet dat de feature uitstaat.

Actual:
Tool retourneert consistent:

📋 Copy-Paste from Conversation

ondanks dat `GET /api/settings/features` bevestigt:

"enable_beta_features": {"value": true, "origin": "file", ...},
"enable_dashboard_screenshot": {"value": true, "origin": "file", ...}

en `GET /api/settings/advanced` bevestigt:

"dashboard_screenshot_engine_url": {"value": "http://0f1cc410-puppet:10000", "origin": "file", ...}


Volgens `docs/beta.md`: "Graceful by design — with one deliberate exception. If the feature is off, both include_screenshot and return_screenshot return the dashboard config / write result with a warnings entry." We krijgen dus consistent de "feature is off" pad, nooit de Puppet-engine fout-pad (timeout/auth), wat erop wijst dat de check die deze tool uitvoert een andere/verouderde waarde leest dan wat `/api/settings/features` rapporteert.

## 💬 Triggering Prompt & Tool Call

**User prompt:** "kijk maar" (gebruiker vroeg te onderzoeken waarom dashboard-screenshots niet werkten ondanks ingeschakelde beta-feature)

**Tool call(s):**
```## 🔧 Environment

- **ha-mcp Version:** 7.8.1
- **Installation Method:** HA Add-on (Supervisor)
- **MCP Transport:** HTTP via add-on ingress
- **MCP Client:** claude-ai 0.1.0
- **AI Model:** Claude Sonnet 4.6 (Anthropic)
- **Operating System:** Home Assistant OS / Supervisor host
- **Home Assistant Version:** 2026.3.2
- **Connection Status:** Connected
- **Entity Count:** 1173

## ⚙️ ha-mcp Configuration

- **enable_websocket:** `True`
- **enable_dashboard_partial_tools:** `True`
- **enable_tool_search:** `False`
- **enable_yaml_config_editing:** `False`
- **enable_code_mode:** `False`
- **enabled_tool_modules:** `all`
- **enable_beta_features:** `True` (origin: file)
- **enable_dashboard_screenshot:** `True` (origin: file)
- **dashboard_screenshot_engine_url:** `http://0f1cc410-puppet:10000` (origin: file)

## 💡 Additional Context

- Gerelateerde HACS-repair was zichtbaar in het systeem rond dezelfde periode: `restart_required` voor `ha_mcp_tools` — mogelijk gerelateerd aan een pending update die de feature-detectie beïnvloedt.
- Puppet add-on (versie 2.5.0) draait en is bereikbaar, met een access_token al geconfigureerd in zijn eigen add-on-opties.
- We komen consistent niet voorbij de "feature disabled" check — nooit een Puppet-specifieke fout (bv. auth/timeout), wat suggereert dat dit vroeg in de tool-flow faalt, vóór de engine ooit wordt aangeroepen.
- Workaround geprobeerd zonder succes: meerdere add-on restarts, nieuwe MCP-sessie/gesprek starten.

[github-actions]

✅ Thanks for the report — this issue has enough information and has been added to the backlog.

🤖 Automated triage by Issue Bot

[Patch76]

Thanks for checking the per-field origin via the settings API before filing — that narrows this down, and it points at a specific gotcha in how those fields are reported.

Tracing the path on current master:

• The screenshot gate is a single check: ha_config_get_dashboard(include_screenshot=True) warns "dashboard screenshot mode is disabled" purely when get_global_settings().enable_dashboard_screenshot is False (tools/tools_config_dashboards.py). Nothing else gates it there — not dashboard_screenshot_engine_url, not enable_beta_features directly.

• enable_dashboard_screenshot is a beta sub-flag behind a master gate. On every Settings build (config.py, _apply_feature_flag_overrides), the override file is applied first, then a master gate runs: if enable_beta_features is False at that moment, every beta sub-flag — including enable_dashboard_screenshot — is force-set False, regardless of what feature_flags.json holds. So the live value of the screenshot flag follows enable_beta_features at build time. There's a log line for exactly this: Beta master toggle is off; forcing enable_dashboard_screenshot=False (was True via env/file).

• The key gotcha in the /api/settings/features output: value and origin are computed from two different sources. value is the live, post-master-gate value off the settings singleton; origin is just "which layer the field is set in" — and origin: "file" is returned whenever the key is present in feature_flags.json, independent of whether the master gate later zeroed the live value. So {value: false, origin: "file"} is a normal, representable state: you set it in the file (hence origin: file), but the master gate forced the runtime value back to false. origin: "file" does not by itself mean the feature is live-on.

That's the most likely shape here: enable_dashboard_screenshot reads origin: "file" (you saved it) while its live value is false because enable_beta_features wasn't True on the singleton at build time — and the tool reads that same live value.

To confirm vs. rule out a deeper bug, could you grab, from the same session as a failing call:

1. The exact /api/settings/features response captured right before a failing ha_config_get_dashboard(include_screenshot=True) — specifically the value (not just origin) for both enable_beta_features and enable_dashboard_screenshot. If enable_dashboard_screenshot shows value: false, the master gate is the blocker and the fix is getting enable_beta_features to live-true. If it genuinely shows value: true at the same moment the tool reports disabled, that's a deeper inconsistency worth digging into.
2. The add-on log around that call — any Beta master toggle is off; forcing enable_dashboard_screenshot=False line (confirms the gate fired), and any Override for … ignoring warnings (a malformed feature_flags.json entry is dropped with a warning).
3. The raw contents of feature_flags.json in the add-on's data dir — does it contain enable_beta_features: true as well as enable_dashboard_screenshot: true?

One aside: dashboard_screenshot_engine_url isn't part of this gate — it only matters once the flag is live-on and the tool actually calls the Puppet engine, so it won't change the "disabled" message either way.

[kingpanther13]

OK so a few things here. I dug into the code a bit more closely and did some testing of my own. The only way to get that message is if either the master beta toggle is off or the screenshot beta toggle is off. On the stable version turning the toggle off, even if you don't restart, will still show the screenshot option in get dashboard tool but will return that message. Also the report issue tool doesn't normally read the beta feature toggles, that isn't a normal part of the template, so your AI basically handmade that part of the report in the template which means it could have hallucinated those values.

So the biggest thing to do right now is to double check your settings in the web UI manually/visually and make sure both of those toggles are actually turned on, and make sure you restart your addon (it'll give you a button to do so) and also make sure you go to your mcp connector settings and refresh the tool list so it gets updated, then try again. If it still isn't working then let me know and we can try some other troubleshooting to get to the bottom of it.

[kingpanther13]

this is what Claude thinks about it, take it with a grain of salt but it may be accurate as well:

Claude tested this on a stable 7.8.1 add-on with the Puppet add-on (0f1cc410_puppet 2.5.0) running. Some concrete results to add:

• That message comes from the core dashboard tools' screenshot path (ha_config_get_dashboard with include_screenshot, ha_config_set_dashboard with return_screenshot). Both check the flag and return before Puppet is ever contacted, so the engine URL and Puppet aren't involved here.

• In /api/settings/features the value field is the same thing the tool checks (get_global_settings().enable_dashboard_screenshot), so on one instance they can't disagree. Claude tested both states: toggle on gives API value true and the tool returns a screenshot; toggle off gives value false and the tool returns the disabled message. So the posted reading (value: true) is the working state, and that's the exact reading Claude got, with the tool working.

• The real question is whether the /api/settings/features you read and the failing tool calls are hitting the same add-on instance. If a failing call ever lines up with value: true on that same instance in the same session, that's a genuine inconsistency worth digging into.

• On the earlier reply: agreed that dashboard_screenshot_engine_url isn't involved in this message. The "master gate forced the value false at build time" angle is probably more than it needs to be. On the file-origin path the toggle takes effect immediately on save with no restart, and it doesn't fit the posted value: true, which points away from the master gate rather than toward it.

• One caveat: Claude couldn't reproduce the failure. On a correctly-enabled setup both screenshot paths just work, so none of this is a confirmed root cause, just what the code and testing show.

[Morrismanski]

Update: visueel bevestigd in de web-UI

Om uit te sluiten dat dit een AI-hallucinatie of een verkeerd gelezen API-waarde was, heb ik de instellingen nu zelf met eigen ogen gecontroleerd in de ha-mcp settings-UI (niet via de AI-tool):

• "Enable beta features" (master toggle, onder "BETA FEATURES (DANGEROUS)"): AAN ✅ (screenshot bevestigd)
• "Enable dashboard screenshot mode (beta)" (sub-toggle): AAN ✅ (screenshot bevestigd)

Beide stonden aan, ik heb opnieuw opgeslagen via "Save advanced settings" en de add-on meermaals herstart (zowel via de web-UI restart-knop als via een directe Supervisor-restart-aanroep). Ook heb ik in dezelfde sessie, met een paar seconden ertussen:

1. GET /api/settings/features aangeroepen → bevestigt enable_beta_features: true en enable_dashboard_screenshot: true, beide origin: "file"
2. Direct daarna ha_config_get_dashboard(include_screenshot=True) aangeroepen → nog steeds: "Screenshot requested but dashboard screenshot mode is disabled."

Dit gebeurde na een verse restart, dus het is geen kwestie van "restart nog niet uitgevoerd" of een gecachte oude waarde van vóór het inschakelen.

Samenvatting van wat is uitgesloten:

• ❌ Toggle stond niet aan → uitgesloten, visueel bevestigd aan
• ❌ Wijzigingen niet opgeslagen → uitgesloten, "Save advanced settings" + restart uitgevoerd, meerdere keren
• ❌ Restart niet uitgevoerd / verkeerde add-on → uitgesloten, restart bevestigd via zowel UI als Supervisor-API, juiste slug (81f33d0f_ha_mcp)
• ❌ Verouderde/gecachte sessie aan de MCP-clientkant → uitgesloten, ook getest na het starten van een volledig nieuw gesprek
• ❌ Dubbele add-on installatie → uitgesloten, slechts één ha_mcp-instance gevonden in de add-on-lijst

Dit lijkt dus een echte inconsistentie tussen wat /api/settings/features rapporteert en wat de daadwerkelijke runtime-check in de dashboard-screenshot-tool gebruikt. Laat het weten als er specifieke debug-logs of een andere diagnostische aanroep nuttig zou zijn om dit verder te isoleren.

[kingpanther13]

That is certainly odd. You're sure that the puppet addon is installed and working too? Try using it by itself and see if it returns screenshots by itself. Also try asking Claude to call the actual dashboard screenshot tool instead of using get dashboard. I confirmed both worked on my side, but there's got to be something else going on with your setup.

[kingpanther13]

A few more ways to isolate it, since you've ruled out the usual suspects:

1. Call the dedicated tool ha_get_dashboard_screenshot directly. It's gated differently from ha_config_get_dashboard: it's only registered at startup when the flag is on, whereas the get/set tools check the flag per call. So if ha_get_dashboard_screenshot comes back as "unknown tool," your MCP server booted with the screenshot flag OFF while /api/settings/features reports it true. That would mean the settings UI and the running server are reading different state, which is the actual bug to chase. If it renders fine, only the get-dashboard path is off.

2. Check the add-on log right after a fresh restart for either of these:

   • Beta master toggle is off; forcing enable_dashboard_screenshot=False (the master gate fired at startup, i.e. the process didn't see beta as on)
   • any feature_flags.json / Override for ... ignoring warning (a malformed entry gets dropped and the flag silently falls back to false)

3. Look at the raw feature_flags.json in the add-on's /data dir (via the SSH or File editor add-on). Confirm it literally contains "enable_beta_features": true and "enable_dashboard_screenshot": true as booleans, not strings.

On Puppet: fine to confirm it works, but it won't explain this message. The "disabled" check returns before Puppet is ever called, so this fails upstream of the engine.

If #1 shows the tool missing or #2 shows the gate firing, the value /api/settings/features reports and the value the tool actually reads are coming from different places.