Start with these, from the folder that holds helppuff.json:

npx @knowtific/helppuff doctor     # checks every piece and prints a fix for each failure
helppuff status                     # what is deployed, where, and today's usage
helppuff ask "a real question" --timing   # the answer, its sources, and each step's time

doctor checks the config, secrets, Cloudflare access, AI Search or the vector index, the Worker and its secrets, the knowledge base, live chat, Telegram, photos and files, and whether the Worker answers. It exits with code 1 when a check fails, and doctor --json is safe to paste into an issue (it contains no secrets).

Jump to: Where to look · Logs · The widget does not appear · Messages visitors see · Wrong or missing answers · Deploy and CLI errors · Cloudflare errors · Dashboard · API errors · Features

helppuff logs                         # live, until Ctrl-C
helppuff logs --method POST           # only POSTs (chat messages, sign-ins…)
helppuff logs --search sessions       # only requests whose log mentions "sessions"
helppuff logs --json --seconds 15     # one JSON result: what arrived in 15 seconds

Start it, then repeat the failing request (send the chat message, reload the page). It uses your wrangler login session, or CLOUDFLARE_API_TOKEN from .env; a token used only for logs needs Workers Tail Read on the Worker. npx wrangler tail knowtific-helppuff-<site> does the same.

Older requests are in the Cloudflare dashboard: Workers & Pages → knowtific-helppuff-<site> → Observability (stored logs, searchable) or Logs → Live. Workers observability is turned on by helppuff deploy.

What the logs contain. Cloudflare logs each request's method, path, HTTP status, outcome and CPU time. HelpPuff adds a JSON line for every failure, on every deployment, with the reason:

{"level":"error","event":"request.error","code":"connector_error","status":502,"detail":"openai_compatible_401:{\"error\":\"invalid api key\"}","method":"POST","path":"/v1/sessions/messages"}
{"level":"error","event":"webhook.emit_failed","type":"lead.created","reason":"TypeError: fetch failed"}

detail and reason are the machine-readable cause. Background work logs the same way: cron.*_failed, live.*_failed, telegram.*_failed, bookings.*_failed, jobs.setup_failed, record.failed. Search Observability for level:error, or helppuff logs --search error. Never message text, contact details or IP addresses. The status and code:

Every error leaves the Worker as the same JSON: {"error": {"code": "…", "message": "…", "retryAfter": 30}}. The public API also sends an X-Request-Id header.

For you, it also says why. When the request is yours (signed in to the dashboard, the admin key the CLI uses, an API key, or helppuff chat and helppuff ask), the error adds reason (what went wrong) and hint (what to do):

{"error": {"code": "connector_error", "message": "The assistant is unavailable right now.",
  "reason": "The model API refused the key (HTTP 401). It said: {\"error\":\"invalid api key\"}",
  "hint": "Store a working key: helppuff secret set <NAME>, then helppuff deploy; helppuff model test checks it"}}

The CLI prints them as the error and its hint, and the dashboard shows them in the error note. Visitors never see them: they get only the message.

The widget never shows a broken state: when something is wrong it does not appear at all. Add ?hpdebug=1 to the page's address and open the browser console:

Then check:

• Is the page's origin allowed? origins in helppuff.json must list the exact scheme and host, including www. if you use it and the port for local testing (http://localhost:3000). helppuff config set or edit it, then helppuff deploy. A missing origin shows in the console as a CORS error on the /config request.
• Does the site have a Content Security Policy? Allow the Worker's address in script-src and connect-src (and img-src if the assistant has an avatar). With Turnstile, also allow https://challenges.cloudflare.com in script-src and frame-src.
• Is it hidden on this page? Check widget.launcher.hideOnPaths.
• Dashboard → Home → Check my site looks for the snippet on your page.

The widget shows the Worker's message as it is. Each one, with its cause:

The site's daily message cap (security.limits.messagesPerSitePerDay, default 500) is reached. It resets at 00:00 UTC. Visitors still get your contact details and the callback form. Raise it if the traffic is real (helppuff config set security.limits.messagesPerSitePerDay 2000, then deploy); see Costs and limits.

The daily AI budget (model.budget.dailyNeurons, default 9,000 of the 10,000 free neurons) is spent, or Workers AI said the account's daily allowance is used. It resets at 00:00 UTC. From 80%, answers get shorter first. On Workers Paid you can raise the budget; on the Free plan the limit is Cloudflare's. helppuff status shows today's use.

A per-visitor limit: 10 messages a minute, 100 a day, 5 new chats an hour or 20 a day from one IP address (the security.limits.* settings). The widget waits for Retry-After. You testing a lot from one address hits these: test with helppuff chat, which is exempt from the per-IP limits, or add your office's address to security.allowIps.

security.limits.messagesPerSession (60) messages in one chat.

The chat is older than security.sessionTtlHours (24), or its token no longer verifies. The second one also happens to every open chat after HELPPUFF_SECRET is rotated. The visitor starts a new chat.

The first: the page's origin is not in origins (above). The second: the data-site in the snippet names no site on this Worker. A visitor whose IP is in security.blockIps does not see the widget at all.

Turnstile refused the browser. Usually the page's hostname is not on the Turnstile widget in Cloudflare. See Turnstile.

The model or backend failed. Busy is a failure a retry can fix: the provider was overloaded, rate limited (429) or down (5xx), or timed out. Unavailable is one it cannot: the key was refused, the model name is wrong, a secret is missing. Find out which:

helppuff model test          # HelpPuff's assistant: says what the provider answered
helppuff doctor              # whole backends (OpenAI, Gemini, Retell, your API): keys and instances

Setting model.fallbackModel tries a second model once when the first one fails.

security.limits.maxMessageLength (1,000 characters).

The visitor sent a form the chat no longer offers (the page was open for a long time, or the settings changed). Refreshing fixes it.

The assistant only answers from what it found. When nothing scores above the threshold it says it is not sure and offers a person: that is on purpose. How the search works: Knowledge base, section 4.

1. See what it found. Dashboard → Knowledge → Test a question, or helppuff ask "…" --json (the sources and their scores).
2. No passage at all? The page may not be learned: helppuff knowledge pages --status error, or Website pages in the dashboard. A page shows Blocked (robots.txt), Skipped (no readable text: often a page drawn by JavaScript; it is rendered in a browser automatically when possible, see knowledge.website.renderJs) or Failed with the reason on the row. Not on the list at all? helppuff discover shows what was found and what is selected; helppuff crawl --urls <url> learns one page.
3. The right passage, but scored low? It may be dropped by the reranker. Lower knowledge.retrieval.minScore a little (0.2 by default), or write the answer yourself (below).
4. Old information? The site is re-crawled on knowledge.website.schedule; helppuff crawl --wait re-learns now. Unchanged pages are skipped by their hash.
5. Add the answer yourself. Dashboard → Knowledge → Your own answers, helppuff knowledge add --title … --text …, a file upload, or a business detail (helppuff knowledge facts set phone="…"). Questions visitors asked that nothing answered collect under Questions to answer (helppuff knowledge gaps).
6. It says something the prompt forbids, or ignores an instruction? The dashboard's Prompt page flags lines that repeat a setting or rule; see Prompt and instructions. Keep a set of real questions and run helppuff eval after every change: Testing and monitoring.

A file failed to learn. The reason is next to it. "No readable text" usually means a scanned PDF (pictures of text); upload a text version. "The upload went missing" means it was not read within a few minutes; upload it again. "This deployment cannot process files yet": helppuff deploy.

The crawl does not start or never finishes. "This deployment has no crawl workflow": helppuff deploy. "The crawl could not start. Try again in a minute": Cloudflare refused to start the background job; try again. helppuff crawl --wait that stops with crawl_timeout has not failed: the crawl continues, follow it with helppuff knowledge status. The Free plan's daily Browser Rendering and neuron limits can slow a large first crawl to the next day.

Replies are slow. helppuff ask "…" --timing prints each step. On Workers AI the model and the reranker take most of it; turning the reranker off (Settings → Advanced → "Double-check answers") saves about half a second, at some cost in accuracy. See AI models: speed, quality, cost.

Every CLI error has a stable code (in --json output) and a hint with the command to run next. Exit codes: 0 ok, 1 error, 2 usage (a wrong flag or a missing --yes), 3 Cloudflare or the admin API refused the credentials, 4 a Cloudflare quota or plan limit, 10 answers needed (needs_input: the JSON lists the questions and the flag for each).

See Upgrading#if-an-upgrade-fails for a failed upgrade and the D1 restore point.

I cannot sign in.

npx @knowtific/helppuff dashboard        # a one-time sign-in link (15 minutes)
helppuff users reset [email protected]     # a new password

Before anyone has an account, helppuff dashboard prints the setup link again. "Too many sign-in attempts. Wait a few minutes and try again" is the sign-in limit, per address and per account. "That email and password do not match" never says which one is wrong, on purpose.

"Please sign in" out of nowhere. The session ended: seven days passed, the password changed, someone signed out everywhere, you were removed from the team, or HELPPUFF_SECRET was rotated.

"Only an admin can do this." You are a member; members reach conversations, jobs, contacts, callbacks and live chat. An admin changes your role under Settings → Team & security (helppuff users role [email protected] admin).

"This deployment has no KV namespace." The deployment is missing a part: helppuff deploy.

More: Locked out, or changing the admin key.

The public API (/api/v1) answers with the same JSON error and an X-Request-Id header.

See The API.

Each has its own page with the details; the common ones:

Open an issue with the output of helppuff doctor --json (it contains no secrets), the failing request's status and JSON body from the browser's Network tab or helppuff logs, and what you expected to happen.