web_extract fails with "No web extract provider configured" despite extract_backend: firecrawl and valid API key

[GitWhoIsThis]

Hermes version: v0.14.0 (2026.5.16)

Config (~/.hermes/config.yaml):
yaml
web:
  search_backend: brave-free
  extract_backend: firecrawl


Env (~/.hermes/.env):

FIRECRAWL_API_KEY=fc-...


Steps to reproduce:
1. Set web.extract_backend: firecrawl in config.yaml
2. Set FIRECRAWL_API_KEY in .env
3. Restart gateway: systemctl --user restart hermes-gateway
4. Call web_extract with any URL

Expected behavior: Firecrawl extracts the page content

Actual behavior:

{"success": false, "error": "No web extract provider configured. Set web.extract_backend to firecrawl, tavily, exa, or parallel."}


Debug output:

=== Config ===
web section: {"backend": "", "search_backend": "brave-free", "extract_backend": "firecrawl", "use_gateway": false}
extract_backend: firecrawl
firecrawl available: True

=== Provider Registry ===
firecrawl provider: None
active extract provider: None


Root cause: _get_extract_backend() correctly returns "firecrawl" and _is_backend_available("firecrawl") returns True. However, get_provider('firecrawl') in agent/web_search_registry.py returns None — the Firecrawl plugin is not being loaded into the registry at import time. This causes the dispatcher in web_tools.py to fall through to the "no provider configured" error path.

Workaround: Manual curl -s "https://r.jina.ai/<URL>" works but Jina's free tier is limited and Google blocks via Jina (429).

[tieroo]

I hit the same issue and tracked down the root cause with the help of Claude Code.
Root cause: missing plugin.yaml files in plugins/web/*/
The _scan_directory_level() function in hermes_cli/plugins.py skips directories without a plugin.yaml file at depth ≥ 1. All web backend plugins (searxng, firecrawl, tavily, exa, parallel, brave-free, ddgs) live at exactly that depth (plugins/web//) and none of them ship a plugin.yaml. As a result, discover_plugins() never registers any web provider, web_search_registry stays empty, and every web_search / web_extract call fails with "No web search provider configured" — regardless of what's in config.yaml or .env.
Workaround
Manually create plugin.yaml with kind: backend in each plugins/web// directory. This is fragile — uv tool upgrade hermes-agent will wipe the files.
Second issue found (bonus)
hermes config set terminal.env_passthrough '["SEARXNG_URL"]' writes a JSON string instead of a YAML list into config.yaml:
yaml# written by hermes config set:
env_passthrough: '["SEARXNG_URL"]'
_load_config_passthrough() in tools/env_passthrough.py checks isinstance(passthrough, list) — a string silently fails this check and the passthrough is ignored. Fix is either defensive parsing in _load_config_passthrough() or fixing hermes config set to write proper YAML lists.
Environment: hermes-agent v0.14.0, Python 3.14.4, Linux, self-hosted Ollama + SearXNG