Bookmark this one instead of reading it

Problems do not arrive in tutorial order: a key that worked for two months returns a 401 one Tuesday morning. So this page is arranged by symptom. Run the three checks, then jump to the section matching your screen.

flowchart TD
  A["Something is wrong"] --> B["Three quick checks"]
  B --> C{"What is on screen?"}
  C -->|"401 / 402 / 429"| D["Key, credit or rate limit"]
  C -->|"404"| E["Ingress and the add-on"]
  C -->|"spinner or blank page"| F["No error code"]
  C -->|"Skill or video step"| G["Workflow sections"]
  C -->|"restarts every minute"| H["Watchdog loop"]
  D --> I["Last 30 log lines"]
  E --> I
  F --> I
  G --> I
  H --> I
  I --> J["GitHub issue"]

Under a minute, and usually enough

1. Check 1

   Is the add-on still running?

   Open Settings → Add-ons → Woow HA Pi Agent. A green Started means running. If it says Stopped or shows red, select Start, allow 30-60 seconds for initialization, and try again.

2. Check 2

   Is a provider actually selected?

   Look at the model selector above the message box. It should name a provider and model, such as GLM / glm-4.6. If it is disabled or reads “No model,” open the Models panel, enter the key and confirm Test succeeds.

3. Check 3

   Can this network reach the internet?

   Open https://www.google.com in a new tab. If that fails, fix the connection first. If browsing works but one provider does not, check its official status page and confirm your network policy allows its API endpoint.

The Info pageAlmost everything here sends you back to this page — for the status, the version, or a toggle.

• The button row along the bottom: Stop, Restart, Uninstall, Open web UI. Stop is offered here because this add-on is running; a stopped one offers Start in its place — check 1 above.
• Current version: 0.12.0 under the title, with a Changelog link beside it. Note the number now; every request for help asks for it.
• Watchdog, on in this shot — it restarts the add-on when it stops answering, and it is the toggle you turn off while diagnosing a restart loop.
• The sidebar switch, labeled Add to sidebar on this build and Show in sidebar in the written documentation. If Pi Agent runs but has no entry in the left menu, this is the switch.

401, 402, 429, 404: four different people saying no

401 Unauthorized

A red “401” or “Unauthorized” in the upper-right corner, and no reply: the provider rejected the credentials. About 90% of the time it is the key.

402 Payment Required, or 429 Too Many Requests

A 402, or a message containing insufficient_balance, “insufficient balance,” “rate limit” or “quota exceeded.” Credentials may be valid; the account has no usable credit, has hit a quota, or is being throttled.

insufficient_balance, credits and quota point at account credit. rate_limit and “too many requests” mean a temporary limit: wait one to two minutes, and do not fire duplicates while you wait.

If the balance is empty, top up at the provider handling your route — GLM bigmodel.cn, OpenAI platform.openai.com, Anthropic console.anthropic.com, OpenRouter openrouter.ai. No restart needed; the next request uses the new balance. Or switch to a second provider and model already configured and tested, checking its charges and limits first.

404 Not Found

“404 Not Found” or “Ingress token invalid,” after selecting Pi Agent in the sidebar or Open Web UI. Nearly always Ingress, the mechanism Home Assistant uses to proxy an add-on's web interface: it issues a temporary keycard, and keycards expire.

No sidebar entry at all

The spinner turns and no answer arrives

Nothing names the problem: the message sends, a spinner appears in the lower-right corner, nothing comes back. Four things, in order.

1. First

   Confirm the basics

   Is a model selected? Does Test succeed for that provider in the Models panel? If either answer is no, fix the configuration first.

2. Second

   Allow for latency

   Reasoning-capable models may take 30-60 seconds or longer before they begin responding. There is no universal ninety-second threshold — latency depends on the model, route, request size and provider load. Send the same prompt to another configured model to tell which it is.

3. Third

   Check whether the network blocks the endpoint

   A corporate VPN, school network, DNS filter or regional policy may block a provider's baseUrl. Opening https://api.openai.com in a browser is a basic connectivity check, not a complete API test — also read the official status page and test DNS and HTTPS from the host that makes the requests. If blocked, switch to another configured route your network and location support.

4. Fourth

   Give Watchdog its minute

   Rarely, pi-web keeps running but stops answering. Wait for automatic recovery: the Watchdog added in v0.10.0 probes /api/home once a minute and asks Supervisor to restart an unresponsive add-on. It notices within 60 seconds, so allow 60-90 seconds in total, then reopen Pi Agent and read the log.

If the request still never completes, open the Log tab and read the final 30 lines around the failed attempt. Copy them, redact anything sensitive, and use them in a GitHub issue.

What working looks likeFinished tool cards with their own timers and costs, a session total in the top bar, and a red Stop in place of Send.

• Each tool card carries its elapsed seconds — write notes.md 5s, read notes.md 2s — with a token and cost line under it: 1,180 in · 70 out · $0.0080. New cards appearing is work still happening.
• Waiting for model… sits under the last card. That line is the honest version of the spinner: the turn has not finished, and the screen is saying what it is on.
• The session total in the top bar — $0.02 here — climbs as work happens. A figure still moving is a useful sign of life.
• The message box has become Steer now / queue follow-up with Steer, Follow-up and a red Stop. That Stop, not Send, is the button for a turn you want to end.

Other quiet symptoms

The sections above cover roughly 90% of what goes wrong. The rest:

When the failure is in a chain of tools

A video workflow strings 5-6 tools together — text-to-speech, Playwright capture, ffmpeg composition, subtitle rendering, rclone upload — so the question is which stage it stopped at.

A Skill will not install, or will not activate

Green status, and a log that keeps starting over

The add-on shows green, but the Log tab shows video-tools-init or pi-web starting again roughly every 60 seconds, and conversations disconnect mid-reply. Watchdog is doing its job: it probes once a minute and restarts an add-on that does not answer. When startup itself fails every time, the protection becomes an endless loop.

Where roughly 90% of answers actually are

Open Settings → Add-ons → Woow HA Pi Agent and select the Log tab; the panel scrolls to the newest entry. A log runs to thousands of lines, so read the last thirty around whatever just failed, and work backward only if the error points at an earlier initialization step.

The Log tabRequest lines, newest at the bottom, a Search logs box above them and a Live badge that says the view is still following.

• Mostly request lines. Each carries a client address, a timestamp, the request and its status code — "GET /api/agent/running/events HTTP/1.1" 200 here. Warnings share the same stream, like the epoll_wait() reported that client prematurely closed connection line a few rows up. Startup messages from bashio and output from pi-web are interleaved in the same view.
• Newest at the bottom. Start there — the last 30 lines are usually enough for a first report.
• Search logs, above the panel, is where you type a keyword; the browser's own Ctrl+F works on what is already on screen. Note that those long hassio_ingress URLs carry a session identifier — redact them before pasting a log anywhere public.

Keywords worth searching for, and what a match usually means:

For more detail, change log_level from info to debug on the Configuration tab, save, then Restart. Reproduce the problem once — the request that returns 401, for example — then set it back to info. Debug output can grow to thousands of lines a minute; do not let /var/log fill up.

If you still need help

Open an issue at https://github.com/WOOWTECH/Woow_ha_pi_agent_add_on/issues, searching existing ones first — “401,” “video-tools,” “blank iframe” — someone may already have reported your symptom. Four things make a report answerable:

• Your Pi Agent version from the top of the Info tab, such as 0.13.1.
• Your Home Assistant version from Settings → About or the system information page.
• The final 30 relevant log lines, in three backticks so GitHub renders a code block.
• Everything you already tried — “restarted, replaced the key, Test succeeds, sending a message still returns 401.”

Write in English if you can. The maintainers read Chinese, but an English report is also readable by people elsewhere who might help; Chinese is fine if English is uncomfortable.

Where to go from here