Troubleshooting
Fixes for the problems people meet most often when installing and running Helpwren.
Installing
"Supabase CLI: not found". Run pnpm install at the repository's root; the CLI is a dev
dependency.
The migrations fail with "password authentication failed". The connection string still says
[YOUR-PASSWORD], or the password has characters that need escaping in a URL. Reset it under
Project Settings → Database, or percent-encode it.
"The Supabase CLI could not apply the migrations", naming a migration that already exists.
The database was changed by hand. supabase migration list --remote=<url> shows what it has.
Never reset a production database to fix this; open an issue with the output.
docker compose says include is not supported. Update Docker; Compose 2.20 or later is
needed.
Port already in use. Change HELPWREN_PORT (Helpwren), API_GW_HTTP_PORT (Supabase) or
POSTGRES_PORT in deploy/docker/.env. POSTGRES_PORT is also the database's internal port.
Signing in
No sign-in code arrives. On Supabase Cloud, the built-in email reaches only members of your
Supabase organisation, a few an hour; set up SMTP (see
Configure Auth). With Docker, check SMTP_* in
deploy/docker/.env, or the test mailbox at http://localhost:8025, and
docker compose logs auth. In the setup wizard, Send a new code shows Supabase's own error.
The email has a link instead of a code. The magic link template was not changed. See Configure Auth, step 2.
/setup sends me to the sign-in page. Someone is already on the team. Sign in as them, or ask
an admin to invite you.
The chat
The chat says it cannot start. Anonymous sign-ins are off in Supabase. See Configure Auth, step 1.
The chat opens empty on my site. Open the browser's console. A Content Security Policy error
about frame-ancestors means the site is not in your
allowed domains.
A conversation from my app fails with "is not one of this install's sources". Add the source. See Add a source.
The live check stays on "Waiting". Open a page of your site that has the snippet, in a fresh tab; the browser keeps the widget's settings for a minute. Allowed domains, if set, must include your site. The check needs the site to be on another address than the install itself.
Emails or pushes are never sent. The scheduled jobs are not being
called, or CRON_SECRET differs between the app and the scheduler. Call a job by hand and read
its answer.
Running
The Helpwren container is unhealthy. Run docker compose logs helpwren. A message naming an
environment variable means .env is missing it; /api/health answering
503 means the database cannot be reached.
/api/health says "migrations": "pending". The build is newer than the database. Run
pnpm helpwren upgrade, or apply the migrations with supabase db push.
Still stuck? Open an issue with what you ran and what it printed, without secrets.