hero_embedder not available #87

New issue

Closed

opened 2026-04-10 05:55:02 +00:00 by Harmen · 1 comment

Harmen commented

2026-04-10 05:55:02 +00:00

Hello!, Nice app but hard (for me) to get started. The service which should run on localhost:3752 fails. See WARN after running hero_books from terminal:

WARN Cannot persist state (hero_embedder unavailable): Health check failed: hero_embedder not available: HTTP error: error sending request for url (http://localhost:3752/rpc)

I followed the binary install instruction on README.

What to do? How to debug?

Hello!, Nice app but hard (for me) to get started. The service which should run on localhost:3752 fails. See WARN after running hero_books from terminal: WARN Cannot persist state (hero_embedder unavailable): Health check failed: hero_embedder not available: HTTP error: error sending request for url (http://localhost:3752/rpc) I followed the binary install instruction on README. What to do? How to debug?

mahmoud referenced this issue from a commit

2026-04-21 05:58:24 +00:00

docs: call out hero_embedder as a prerequisite and explain degraded mode

mahmoud referenced this issue

2026-04-21 05:58:42 +00:00

docs: call out hero_embedder as a prerequisite and explain degraded mode #96

mahmoud commented

2026-04-21 05:59:05 +00:00

Owner

Hi — thanks for the clear report, and sorry for the rough onboarding. The WARN line you are seeing is informational, not fatal. Hero Books is actually working; it is just running in degraded mode because hero_embedder — a separate service that provides vector search, Q&A embedding, and semantic retrieval — is not running on your machine yet. The reader UI, PDF export, and Markdown browsing should all work as-is.

What to do

If you only need the reader UI and PDF output: you are already done. Ignore the warning. You can browse books, generate PDFs, and use the Markdown views without hero_embedder.

If you want vector search / Q&A / AI features: install and start hero_embedder before starting hero_books.

Repo: https://forge.ourworld.tf/lhumina_code/hero_embedder (install instructions are in its README).
Default endpoint: TCP http://localhost:3752/rpc or Unix socket ~/hero/var/sockets/hero_embedder.sock.
Once it is running, restart Hero Books (hero_books --stop && hero_books --start) and the warning will go away.

Recommended (Hero-native path): the supported way to bring both services up together is through hero_skills, which installs everything under hero_proc supervision:

# from a shell with hero_skills loaded
service_embedder install ; service_embedder start
service_books install    ; service_books start

This wires up sockets, logs, and restart policy automatically, and is what we test against.

What we changed on our side

You hit a real documentation gap. The README and the server manual mentioned hero_embedder only in passing and did not flag it as a prerequisite. We just opened a PR to fix that:

#96 — #96

Once merged, the README will have:

A Prerequisites section at the top of Installation that explains the hero_embedder dependency, what features it enables, and what "degraded mode" means.
A Troubleshooting section that explains the WARN Cannot persist state (hero_embedder unavailable) line you saw, so the next person does not get blindsided the way you did.
A recommended hero_skills-based install path for running the whole stack.

docs/manual/server.md also gains a dedicated "External Dependency: hero_embedder" section with the default endpoint and degraded-mode behavior.

Please let us know if the workaround gets you running, and whether anything else in the onboarding tripped you up — we would rather find out now than have another person hit the same wall.

Hi — thanks for the clear report, and sorry for the rough onboarding. The `WARN` line you are seeing is **informational, not fatal**. Hero Books is actually working; it is just running in degraded mode because `hero_embedder` — a separate service that provides vector search, Q&A embedding, and semantic retrieval — is not running on your machine yet. The reader UI, PDF export, and Markdown browsing should all work as-is. ## What to do **If you only need the reader UI and PDF output:** you are already done. Ignore the warning. You can browse books, generate PDFs, and use the Markdown views without `hero_embedder`. **If you want vector search / Q&A / AI features:** install and start `hero_embedder` before starting `hero_books`. - Repo: https://forge.ourworld.tf/lhumina_code/hero_embedder (install instructions are in its README). - Default endpoint: TCP `http://localhost:3752/rpc` or Unix socket `~/hero/var/sockets/hero_embedder.sock`. - Once it is running, restart Hero Books (`hero_books --stop && hero_books --start`) and the warning will go away. **Recommended (Hero-native path):** the supported way to bring both services up together is through [`hero_skills`](https://forge.ourworld.tf/lhumina_code/hero_skills), which installs everything under `hero_proc` supervision: ```nushell # from a shell with hero_skills loaded service_embedder install ; service_embedder start service_books install ; service_books start ``` This wires up sockets, logs, and restart policy automatically, and is what we test against. ## What we changed on our side You hit a real documentation gap. The README and the server manual mentioned `hero_embedder` only in passing and did not flag it as a prerequisite. We just opened a PR to fix that: - **#96** — https://forge.ourworld.tf/lhumina_code/hero_books/pulls/96 Once merged, the README will have: - A `Prerequisites` section at the top of Installation that explains the `hero_embedder` dependency, what features it enables, and what "degraded mode" means. - A `Troubleshooting` section that explains the `WARN Cannot persist state (hero_embedder unavailable)` line you saw, so the next person does not get blindsided the way you did. - A recommended `hero_skills`-based install path for running the whole stack. `docs/manual/server.md` also gains a dedicated "External Dependency: hero_embedder" section with the default endpoint and degraded-mode behavior. Please let us know if the workaround gets you running, and whether anything else in the onboarding tripped you up — we would rather find out now than have another person hit the same wall.

mahmoud self-assigned this

2026-04-21 05:59:51 +00:00

mahmoud added this to the ACTIVE project

2026-04-21 05:59:52 +00:00

mahmoud added this to the now milestone

2026-04-21 05:59:54 +00:00

mahmoud closed this issue

2026-04-21 06:13:02 +00:00

mahmoud referenced this issue from a commit

2026-04-21 06:27:58 +00:00

chore: align hero_books with hero_sockets and simplify the README

mahmoud referenced this issue