searxng/searxng · error · ValueError

missing required config `base_url`

Error message

missing required config `base_url`

What it means

Anna's Archive engine's setup() hook requires a `base_url` setting because the site has no stable official domain (domains rotate due to takedowns). Without it the engine cannot build request URLs, so it raises at setup time and the engine is not usable.

Source

Thrown at searx/engines/annas_archive.py:106

aa_ext: str = ""
"""Filter Anna's results by a file ending.  Common filters for example are
``pdf`` and ``epub``.

.. note::

   Anna's Archive is a beta release: Filter results by file extension does not
   really work on Anna's Archive.

"""


def setup(_engine_settings: dict[str, t.Any]) -> bool:
    """Check of engine's settings."""

    traits: EngineTraits = EngineTraits(**ENGINE_TRAITS["annas archive"])

    if not base_url:
        raise ValueError("missing required config `base_url`")

    if aa_content and aa_content not in traits.custom["content"]:
        raise ValueError(f"invalid setting content: {aa_content}")

    if aa_sort and aa_sort not in traits.custom["sort"]:
        raise ValueError(f"invalid setting sort: {aa_sort}")

    if aa_ext and aa_ext not in traits.custom["ext"]:
        raise ValueError(f"invalid setting ext: {aa_ext}")

    return True


def _get_base_url_choice() -> str:
    if isinstance(base_url, list):
        return random.choice(base_url)

    return base_url

View on GitHub (pinned to 9fea41204f)

Solutions

1. Add `base_url: https://annas-archive.org` (or a currently working mirror) to the annas_archive engine block in settings.yml
2. Verify the URL responds before committing it to config
3. Alternatively disable the engine (`disabled: true` → remove/omit) if you don't want to maintain a domain

Example fix

# before (settings.yml)
- name: annas archive
  engine: annas_archive
  shortcut: aa

# after
- name: annas archive
  engine: annas_archive
  shortcut: aa
  base_url: https://annas-archive.org

entry = next(e for e in settings['engines'] if e.get('engine') == 'annas_archive')
if not entry.get('base_url'):
    entry['base_url'] = 'https://annas-archive.org'  # or disable the engine

def annas_engine_ready(entry: dict) -> bool:
    return isinstance(entry.get('base_url'), str) and entry['base_url'].startswith('http')

try:
    annas_archive.setup(entry)
except ValueError as e:
    if 'missing required config `base_url`' in str(e):
        log.warning('annas_archive disabled until base_url is configured')
    else:
        raise

When it happens

Trigger: Enabling the annas_archive engine in settings.yml without a `base_url` key. setup(engine_settings) runs during engine initialization (once, at startup or when the engine is first activated) and returns bool on success.

Common situations: New searxng installs where the engine is enabled but base_url was never configured; copying example configs that omit it; the known instance list (searx/data/ahmia etc. style) not providing a fallback here — this engine mandates explicit configuration.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• adobe_stock engine: adobe_order is unset
• adobe_stock engine: adobe_content_types is unset
• invalid setting content: {aa_content}
• invalid setting sort: {aa_sort}
• invalid setting ext: {aa_ext}

AI-assisted analysis of searxng/searxng@9fea41204f (2026-08-27). Data as JSON: /api/errors/12d3b432144c3b9d. Report an issue: GitHub.