oraios/serena · error · SolidLSPException

Resource paths inside the vscode-java

Error message

Resource paths inside the vscode-java {vscode_java_version} VSIX are not pinned in serena (known: {cls.INITIAL_VSCODE_JAVA_VERSION}, {cls.DEFAULT_VSCODE_JAVA_VERSION}). Either remove the 'vscode_java_version' override (defaults to {cls.DEFAULT_VSCODE_JAVA_VERSION}), or use upstream JDTLS mode by setting both 'jdtls_path' and 'lombok_path' in ls_specific_settings.java (no pinning required).

What it means

This SolidLSPException is raised when 'vscode_java_version' is overridden to a version for which Serena has no pinned resource paths inside the vscode-java VSIX. Serena only knows the internal file layout for explicitly pinned versions (INITIAL and DEFAULT), so unknown overrides fail fast with an explanation of the two supported alternatives.

Solutions

Remove the 'vscode_java_version' override so the default pinned version is used.
Switch to upstream JDTLS mode by setting both 'jdtls_path' and 'lombok_path' in ls_specific_settings.java (no version pinning required).
Upgrade Serena to a release that pins the vscode-java version you need.
Verify the override string exactly matches a pinned version constant in eclipse_jdtls.py.

Example fix

// before
{"ls_specific_settings": {"java": {"vscode_java_version": "1.34.0"}}}
// after
{"ls_specific_settings": {"java": {}}}

Defensive patterns

Strategy: validation

Validate before calling

java = settings.get('ls_specific_settings', {}).get('java', {})
v = java.get('vscode_java_version')
if v is not None and v not in (KNOWN_INITIAL_VSCODE_JAVA_VERSION, KNOWN_DEFAULT_VSCODE_JAVA_VERSION):
    java.pop('vscode_java_version')  # fall back to the pinned default

Type guard

def vscode_java_version_is_pinned(java_settings: dict, pinned: set[str]) -> bool:
    v = java_settings.get('vscode_java_version')
    return v is None or v in pinned

Try / catch

try:
    ls = SolidLSP(java_config)
except SolidLSPException as e:
    if 'not pinned in serena' in str(e):
        java_config['ls_specific_settings']['java'].pop('vscode_java_version', None)
        ls = SolidLSP(java_config)
    else:
        raise

Prevention

Avoid overriding vscode_java_version unless you know Serena pins that version.
After upgrading Serena, re-check any vscode_java_version override against its new pinned constants.
Use upstream JDTLS mode (jdtls_path + lombok_path) if you need a specific JDTLS version without pinning.

When it happens

Trigger: _setup_runtime_dependencies reads custom_settings['vscode_java_version']; the value matches neither INITIAL_VSCODE_JAVA_VERSION nor DEFAULT_VSCODE_JAVA_VERSION, so no VSIX path table exists for it.

Common situations: User bumps vscode_java_version to a newer upstream release hoping for newer Java support; copy-pasted version string from vscode-java changelog; default version changed in a Serena upgrade while an old override lingers in config.

Related errors

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

Appendix: source

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

            gradle_version = custom_settings.get("gradle_version", cls.DEFAULT_GRADLE_VERSION)
            vscode_java_version = custom_settings.get("vscode_java_version", cls.DEFAULT_VSCODE_JAVA_VERSION)

            # install-dir name per the version-pinning convention (see module-level block):
            # INITIAL -> legacy unversioned dir; everything else -> "{name}-{resolved}" subdir
            vscode_java_dirname = (
                "vscode-java" if vscode_java_version == cls.INITIAL_VSCODE_JAVA_VERSION else f"vscode-java-{vscode_java_version}"
            )

            # Resolve internal VSIX paths (JRE / Lombok / launcher filenames). For pinned versions
            # these are known; for any other user-supplied version we bail out — guessing would
            # silently produce broken paths at JDTLS launch time, which is a worse UX than failing
            # fast here with a pointer to upstream-JDTLS mode (which doesn't need pinned paths).
            if vscode_java_version == cls.INITIAL_VSCODE_JAVA_VERSION:
                vsix_paths = cls.INITIAL_VSCODE_JAVA_PATHS
            elif vscode_java_version == cls.DEFAULT_VSCODE_JAVA_VERSION:
                vsix_paths = cls.DEFAULT_VSCODE_JAVA_PATHS
            else:
                raise SolidLSPException(
                    f"Resource paths inside the vscode-java {vscode_java_version} VSIX are not pinned in serena "
                    f"(known: {cls.INITIAL_VSCODE_JAVA_VERSION}, {cls.DEFAULT_VSCODE_JAVA_VERSION}). "
                    f"Either remove the 'vscode_java_version' override (defaults to {cls.DEFAULT_VSCODE_JAVA_VERSION}), "
                    f"or use upstream JDTLS mode by setting both 'jdtls_path' and 'lombok_path' in "
                    f"ls_specific_settings.java (no pinning required)."
                )

            vscode_java_configs: dict[str, VSCodeJavaConfig] = {
                "osx-arm64": VSCodeJavaConfig(
                    jre_home_path=f"extension/jre/{vsix_paths.jre_version}-macosx-aarch64",
                    jre_path=f"extension/jre/{vsix_paths.jre_version}-macosx-aarch64/bin/java",
                    lombok_jar_path=f"extension/lombok/{vsix_paths.lombok_jar_basename}",
                    jdtls_launcher_jar_path=f"extension/server/plugins/{vsix_paths.equinox_launcher_basename}",
                    jdtls_readonly_config_path="extension/server/config_mac_arm",
                ),
                "osx-x64": VSCodeJavaConfig(
                    jre_home_path=f"extension/jre/{vsix_paths.jre_version}-macosx-x86_64",
                    jre_path=f"extension/jre/{vsix_paths.jre_version}-macosx-x86_64/bin/java",

View on GitHub (pinned to 7fcbca7e62)