oraios/serena · error · ValueError

Tool timeout must be at least 10 seconds, but is {tool_timeo

Error message

Tool timeout must be at least 10 seconds, but is {tool_timeout} seconds

What it means

Raised by Project.create_language_server_manager (src/serena/project.py:508) when serena_config.tool_timeout is configured to a positive value below 10 seconds. The tool timeout must be at least 10s because the language-server timeout is derived as tool_timeout - 5 and single LS calls need headroom.

Source

Thrown at src/serena/project.py:508

    def create_language_server_manager(self) -> LanguageServerManager:
        """
        Creates the language server manager for the project, starting one language server per configured programming language.

        :return: the language server manager, which is also stored in the project instance
        """
        try:
            # ensure that the project configuration, particularly the list of languages is complete,
            # despite asynchronous first-time project configuration generation (which may not have completed yet)
            self.project_config.await_asynchronous_completion()

            # determine timeout to use for LS calls
            tool_timeout = self.serena_config.tool_timeout
            if tool_timeout is None or tool_timeout < 0:
                ls_timeout = None
            else:
                if tool_timeout < 10:
                    raise ValueError(f"Tool timeout must be at least 10 seconds, but is {tool_timeout} seconds")
                ls_timeout = tool_timeout - 5  # the LS timeout is for a single call, it should be smaller than the tool timeout

            # if there is an existing instance, stop its language servers first
            if self.language_server_manager is not None:
                log.info("Stopping existing language server manager ...")
                self.language_server_manager.stop_all()
                self.language_server_manager = None

            log.info(f"Creating language server manager for {self.project_root}")
            self._language_server_manager_init_error = None
            ls_specific_settings = dict(self.serena_config.ls_specific_settings)
            if self.project_config.ls_specific_settings:
                if self.is_trusted():
                    ls_specific_settings.update(self.project_config.ls_specific_settings)
                else:
                    log.warning(
                        f"Project path {self.project_root} is not trusted, ignoring LS-specific settings from project configuration. "
                        "To trust the project, modify the trusted path patterns in the global configuration."

View on GitHub (pinned to 7fcbca7e62)

Solutions

Set tool_timeout to at least 10 in the Serena configuration (e.g. 30–60 for large projects)
Or set tool_timeout to None / a negative value to disable the timeout entirely
Restart the language server manager after changing the configuration

Example fix

// before (config)
tool_timeout = 5
// after
tool_timeout = 30

Defensive patterns

Strategy: validation

Validate before calling

t = cfg.tool_timeout
if t is not None and 0 <= t < 10:
    raise ValueError('tool_timeout must be >= 10 or negative/None to disable')

Try / catch

try:
    manager = project.create_language_server_manager(...)
except ValueError as e:
    logging.error('Fix tool_timeout config: %s', e)
    raise

Prevention

Set tool_timeout >= 10 in config
Use 30–60s for large projects
Use None/negative to disable timeouts deliberately

When it happens

Trigger: Setting tool_timeout to 1–9 seconds (or 0 with a non-None config) in serena config, then starting any language-server-backed operation (indexing, get_symbols_overview, find_symbol, etc.).

Common situations: Users tuning timeouts too aggressively for large projects; copying example configs with small timeout values; CI environments that shrink timeouts to fail fast.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/7e7efb3362d08342. Report an issue: GitHub.