oraios/serena · error · FileNotFoundError

Gradle user home directory not found: {custom_gradle_home}.

Error message

Gradle user home directory not found: {custom_gradle_home}. Fix: create the directory, update path in ~/.serena/serena_config.yml (ls_specific_settings -> java -> gradle_user_home), or remove the setting to use default (~/.gradle)

What it means

A custom Gradle user home configured via ls_specific_settings.java.gradlele_user_home in ~/.serena/serena_config.yml must be an existing directory; JDTLS passes it as the Gradle user home for dependency resolution. If the directory is missing, _create_base_initialize_params raises FileNotFoundError with instructions to fix or drop the setting.

Source

Thrown at src/solidlsp/language_servers/eclipse_jdtls.py:944

            maven_settings_path = default_maven_settings_path
            log.info(f"Using Maven settings from default location: {maven_settings_path}")
        else:
            maven_settings_path = None
            log.info(f"Maven settings not found at default location ({default_maven_settings_path}), will use JDTLS defaults")

        # Gradle user home: default to ~/.gradle
        default_gradle_home = os.path.join(os.path.expanduser("~"), ".gradle")
        custom_gradle_home = self._custom_settings.get("gradle_user_home")
        if custom_gradle_home is not None:
            # User explicitly provided a path
            if not os.path.exists(custom_gradle_home):
                error_msg = (
                    f"Gradle user home directory not found: {custom_gradle_home}. "
                    f"Fix: create the directory, update path in ~/.serena/serena_config.yml (ls_specific_settings -> java -> gradle_user_home), "
                    f"or remove the setting to use default (~/.gradle)"
                )
                log.error(error_msg)
                raise FileNotFoundError(error_msg)
            gradle_user_home = custom_gradle_home
            log.info(f"Using Gradle user home from custom location: {gradle_user_home}")
        elif os.path.exists(default_gradle_home):
            gradle_user_home = default_gradle_home
            log.info(f"Using Gradle user home from default location: {gradle_user_home}")
        else:
            gradle_user_home = None
            log.info(f"Gradle user home not found at default location ({default_gradle_home}), will use JDTLS defaults")

        # Lombok-generated symbols (getX/setX/builder()/equals/hashCode/toString/...): JDTLS filters
        # these out of documentSymbol results by default. Without them, find_symbol/get_symbols_overview
        # return only user-written sources, which breaks navigation around @Data/@Builder/@Getter/@Setter
        # classes. Default to True so agentic workflows can find_symbol -> replace_symbol_body on generated
        # members. Requires JDTLS commit b2d8952 or newer (vscode-java >= 1.53.0, or upstream JDTLS
        # snapshot after 2026-02-24); older servers ignore the unknown preference key silently.
        # See eclipse-jdtls/eclipse.jdt.ls#3706.
        lombok_show_generated = self._custom_settings.get("lombok_show_generated", True)

View on GitHub (pinned to 7fcbca7e62)

Solutions

Create the directory: mkdir -p <custom_gradle_home>
Update ls_specific_settings -> java -> gradle_user_home in ~/.serena/serena_config.yml to the correct directory
Or remove the setting to fall back to the default (~/.gradle)
Confirm with: test -d <path> && echo exists

Example fix

// before
$ gradle_user_home: /opt/gradle-home   # never created
// after
$ mkdir -p /opt/gradle-home
# or remove the gradle_user_home line from serena_config.yml

Defensive patterns

Strategy: validation

Validate before calling

import os, yaml
cfg = yaml.safe_load(open(os.path.expanduser('~/.serena/serena_config.yml')))
g = cfg.get('ls_specific_settings', {}).get('java', {}).get('gradle_user_home')
if g and not os.path.isdir(os.path.expanduser(g)):
    print(f"gradle user home missing: {g}")

Type guard

def gradle_home_ok(path: str | None) -> bool:
    import os
    return path is None or os.path.isdir(os.path.expanduser(path))

Try / catch

try:
    server = LanguageServer.create(LanguageServerId.JAVA, ...)
except FileNotFoundError as e:
    logger.error("Gradle home issue: %s", e)
    # mkdir -p the directory or drop the setting, then retry

Prevention

Create the gradle_user_home directory before referencing it in config
Pre-create directories in Dockerfiles/CI before launching Serena
Avoid custom gradle_user_home unless needed; default ~/.gradle is safer
Re-check the entry after cleaning ~/.gradle or moving caches

When it happens

Trigger: Starting the JDTLS language server while gradle_user_home in serena_config.yml points to a directory that does not exist — deleted cache dir, typo, or a path only present on another machine.

Common situations: Pointing at a moved ~/.gradle directory; cleaning ~/.gradle and forgetting the custom entry; CI containers lacking the configured GRADLE_USER_HOME; typos like /home/usr/.gradle.

Related errors

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