oraios/serena · error · FileNotFoundError

Provided maven settings file not found

Error message

Provided maven settings file not found: {custom_maven_settings_path}. Fix: create the file, update path in ~/.serena/serena_config.yml (ls_specific_settings -> java -> maven_user_settings), or remove the setting to use default ({default_maven_settings_path})

What it means

Serena lets you point JDTLS at a custom Maven settings.xml via ls_specific_settings.java.maven_user_settings in ~/.serena/serena_config.yml. When that configured file does not exist, _create_base_initialize_params raises FileNotFoundError so dependency resolution doesn't silently run with defaults. The message lists the default path that would be used instead.

Solutions

Create the settings file at the configured path (e.g., copy a template or your corporate settings.xml)
Update ls_specific_settings -> java -> maven_user_settings in ~/.serena/serena_config.yml to the correct path
Or remove the maven_user_settings key entirely so the default (~/.m2/settings.xml) is used
Run ls -l <configured path> to confirm the exact file exists

Example fix

# before (serena_config.yml)
maven_user_settings: /home/user/.m2/setting.xml   # typo
// after
maven_user_settings: /home/user/.m2/settings.xml

Defensive patterns

Strategy: validation

Validate before calling

import os, yaml
cfg = yaml.safe_load(open(os.path.expanduser('~/.serena/serena_config.yml')))
p = cfg.get('ls_specific_settings', {}).get('java', {}).get('maven_user_settings')
if p and not os.path.isfile(os.path.expanduser(p)):
    print(f"maven settings file missing: {p}")

Type guard

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

Try / catch

try:
    server = LanguageServer.create(LanguageServerId.JAVA, ...)
except FileNotFoundError as e:
    logger.error("Maven settings issue: %s", e)
    # remove maven_user_settings from config or create the file, then retry

Prevention

Verify the settings.xml path right after editing serena_config.yml
Use absolute, expanded paths (~/...) in config
Don't delete corporate settings.xml without updating the config
Keep a template settings.xml committed for CI environments

When it happens

Trigger: Starting the JDTLS language server with a maven_user_settings value in serena_config.yml whose file path does not exist — wrong filename, file deleted, or relative path resolved differently than expected.

Common situations: Copying a settings.xml path from another machine; deleting ~/.m2/settings.xml or a corporate settings file during cleanup; typo like 'setting.xml' instead of 'settings.xml'; mount not present in CI.

Related errors

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

Appendix: source

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

        # Look into https://github.com/eclipse/eclipse.jdt.ls/blob/master/org.eclipse.jdt.ls.core/src/org/eclipse/jdt/ls/core/internal/preferences/Preferences.java to understand all the options available

        repo_uri = pathlib.Path(self.repository_root_path).as_uri()

        # Load user's Maven and Gradle configuration paths from ls_specific_settings["java"]

        # Maven settings: default to ~/.m2/settings.xml
        default_maven_settings_path = os.path.join(os.path.expanduser("~"), ".m2", "settings.xml")
        custom_maven_settings_path = self._custom_settings.get("maven_user_settings")
        if custom_maven_settings_path is not None:
            # User explicitly provided a path
            if not os.path.exists(custom_maven_settings_path):
                error_msg = (
                    f"Provided maven settings file not found: {custom_maven_settings_path}. "
                    f"Fix: create the file, update path in ~/.serena/serena_config.yml (ls_specific_settings -> java -> maven_user_settings), "
                    f"or remove the setting to use default ({default_maven_settings_path})"
                )
                log.error(error_msg)
                raise FileNotFoundError(error_msg)
            maven_settings_path = custom_maven_settings_path
            log.info(f"Using Maven settings from custom location: {maven_settings_path}")
        elif os.path.exists(default_maven_settings_path):
            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), "

View on GitHub (pinned to 7fcbca7e62)