Common problems and what to check

Most problems with Charyl trace back to one of a handful of causes — a chat route with nothing to talk to, a service that hasn’t finished restarting, or a step that got skipped during setup. This guide walks through the ones we see, symptom first.

Charyl’s chat isn’t answering

Check whether the rest of the app is responsive

If pages generally, not just chat, are slow or unreachable, the problem is the box itself — see “the box’s friendly name doesn’t resolve” below before assuming it’s Charyl specifically.
Know what route chat is on

Chat picks automatically, in order: a capable local model, then your own AI-provider key, then Charyl Cloud if your subscription is active. If none of those apply, there’s nothing to answer with.
If you rely on Charyl Cloud, check your subscription

A lapsed subscription leaves chat with no route, silently. The in-app message for this state was written for onboarding, not for a lapsed subscriber, so it won’t clearly tell you to resubscribe — that’s a known gap, not something you’re missing.

One error message, several causes

A stalled or failed answer currently shows the same generic message regardless of why. Retrying only helps if the cause was a slow connection — it won’t help for a used-up usage budget or a lapsed subscription, both of which need a different fix.

Search over your documents comes back empty

Zero results almost always means nothing cleared the similarity bar for that phrasing, not that the document was never indexed.

Rephrase, or be more specific

A search for “manual” might miss a document that would surface for “installation guide,” or for the appliance’s own name.
Confirm the document is actually attached

Open the asset or record directly and check its document list. If it’s there, indexing worked — the search itself is just narrower than a full-text search.
On a self-hosted box, confirm the local embedding model is running
Document search depends on a local embedding model being reachable. If search is empty across the board, not just for one document, check the logs for the service that handles it:
```
docker compose logs singer-charyl
```

Private records behave differently on purpose

If a document belongs to a Home Record you marked private, its contents never reach Charyl at all, even though the record itself still shows as existing. That’s the private-record boundary working as designed, not a search failure.

You’ve lost access to the admin account

There’s no email-based password reset today. Recovery is a two-step edit to your .env file.

Set two variables

ADMIN_PASSWORD=<a-new-password>
ADMIN_RESET_PASSWORD=true

Restart once
```
docker compose up -d
```
On the next startup, the box re-hashes ADMIN_PASSWORD into the seeded admin account’s credentials.
Log in, then turn the flag back off

Remove ADMIN_RESET_PASSWORD and restart again — leaving it set means the password resets to whatever’s in .env on every future restart.

The box’s friendly name doesn’t resolve on your network

A box advertises itself under a short local name, but that only works from a Linux Docker host — it’s a no-op on Mac and Windows setups.

Use the box's LAN IP address instead

From another device on the same network, the IP address always works, friendly name or not.
Use localhost, if you're on the box itself

http://localhost:8080 works from the same machine the box is running on, regardless of the friendly-name limitation.

Not a bug to chase

This is a known, named limitation of how the friendly name gets advertised on non-Linux Docker hosts — the IP address is the documented way around it, not a workaround waiting on a fix.

A service won’t pull, during setup or during an update

Check registry authentication
During the private-testing period, pulling images needs a signed-in registry session:
```
docker login ghcr.io -u "$GHCR_USERNAME" --password-stdin <<< "$GHCR_READ_TOKEN"
```
If it's specifically the auto-updater failing, check its own environment
Logging in by hand on the box doesn’t cover the updater — it pulls from inside its own container, which needs GHCR_USERNAME and GHCR_READ_TOKEN set in .env to reach the registry itself. Confirm with:
```
docker compose exec singer-updater printenv GHCR_USERNAME
```

`docker compose down -v` and now nothing works

This is expected, not a bug. Your secrets and your database are a matched pair by design — resetting one without the other causes a password mismatch.

The safe fix

Bring both down together, then back up:

docker compose down -v
docker compose up -d

This comes back up clean, with a freshly generated admin password printed once in the log.

Setup is stuck asking for an AI key

If you chose to self-host during setup, and your box has no capable local model and no AI-provider key, the wizard stops at the key step — by design, it doesn’t move backward.

Use Skip at that step

Skip is available specifically there, and lets you finish the rest of setup without a key.
Connect to Charyl Cloud afterward, if you'd rather not manage a key

Settings shows a banner offering to connect your home to Charyl Cloud once setup is done.
Or add your own key later

The app’s AI provider settings accept a key any time, whether or not you used Skip during setup.

Something broke after an update

If you're on Charyl Cloud

Updates are already health-checked for up to ten minutes after applying, and an unhealthy update rolls itself back automatically. If something broke and then quietly returned to normal, that’s this working as intended.
If you're self-hosting without a subscription
Self-applying, health-checked updates are a Charyl Cloud feature — without a subscription, updates are manual, and there’s no automatic rollback. Check the logs for the service that looks wrong:
```
docker compose logs -f <service>
```

Undoing a manual update

SINGER_VERSION and CHARYL_VERSION in .env are what pin your running release — setting one back to your last-known-good version, then pulling again, is the way back if a hand-applied update is the cause.

Filing a report when the box was never connected to Charyl Cloud

/bug and /request work either way, but an unpaired box has nothing to upload to. Charyl offers copy to clipboard and download as a file instead, so the report still exists — it just isn’t sent automatically. Nothing is silently lost.

If none of these match what you’re seeing, the community board is the place to describe it — a report we haven’t seen before is exactly the kind of thing worth a fresh pair of eyes.