Troubleshooting

Start every investigation with the same two commands, then jump to the matching symptom.

helpin doctor --dir /srv/helpin
helpin status --dir /srv/helpin

Doctor prints the next step for anything it finds. Status shows which service is unhealthy. The one-shot jobs helpin-migrate, temporal-schema, and temporal-namespace are expected to show exited (0).

Before sharing logs: they can contain customer data. Review excerpts, and never post .env, signed attachment URLs, or backups.

Installation

Images can't be downloaded

Symptoms: access denied, manifest unknown, or pull timeouts during install.

Check the host can reach ghcr.io and Docker Hub.
Install a published release. Unreleased tags aren't publicly pullable.
Behind a corporate proxy, configure Docker's own proxy settings.

Install fails the memory or disk check

Docker needs 8 GB RAM available. An 8 GB server reports about 7.7 GiB, which is accepted. The check warns from 6 GiB and fails below that. On Docker Desktop, raise the memory limit in its settings. Also check free space on Docker's data disk, not just the installation directory.

A port is already in use

Choose other ports with helpin configure, or --port, --help-port, and --storage-port at install time.

Dashboard

The dashboard doesn't load or can't reach the API

helpin logs helpin-api helpin-migrate. The API waits for migrations and infrastructure to be ready.
On the server itself, open http://localhost:8085. From another computer, localhost means that computer.
For public access, check DNS, HTTPS, and your proxy. See Deploy on a public server.
Check APP_BASE_URL matches the exact public origin.

Fix .env, then run helpin restart. Don't regenerate encryption keys to fix connectivity.

Messages only appear after a refresh

Your reverse proxy isn't passing WebSockets. Forward the Upgrade and Connection headers, disable buffering, and set a 3,600-second read timeout. Then check helpin logs helpin-api nats redis.

The exact website origin, with scheme and port, is in Settings → Chat widget. An empty list blocks everyone.
The snippet on your site is current and points at this installation.
The browser console shows no CSP, mixed-content, or origin errors.

See Connect the chat widget. Don't disable origin or identity checks as a workaround.

Attachments don't upload or display

PUBLIC_STORAGE_URL must be public and use HTTPS, be allowed in your site's CSP, and the garage service must be healthy. Never make the storage bucket public to work around this.

AI and agents

An agent doesn't respond

Settings → AI has a connected provider, a profile, and a workspace default.
The model name is valid for your provider.
Check the logs: helpin logs agent-runtime agent-runtime-worker helpin-api nats.

If the runtime shows progress but Helpin looks stuck, the API isn't receiving runtime events. Check helpin-api and nats. See AI providers & knowledge search.

Search is keyword-only

No embeddings source is configured. Add an OpenAI or OpenRouter key on the server or in the workspace. Anthropic can't provide embeddings.

Email

Invitations or password resets don't arrive

Send a test from Settings → System status, then check your provider's delivery logs and your SPF and DKIM records. Credentials require TLS and AUTH PLAIN. See Application email. Until email works, copy invite links from Settings → Members.

Data

A migration, restore, or upgrade failed

Keep the failing migration version and the redacted error. Don't edit applied SQL, reset the migration ledger, or delete volumes. Recover with the backup taken before the change. See Back up and restore and Upgrade Helpin.

A command says the installation is locked

Another helpin command is running, or one was killed. Confirm the process ID in .NAME.helpin.lock is no longer running before you remove the lock.

Still stuck?

Open an issue on GitHub with your release version, the helpin doctor output, and redacted logs. Report security vulnerabilities privately, following the security checklist.

Was this article helpful?