oraios/serena · error · RuntimeError

Failed to find lua-language-server executable after extracti

Error message

Failed to find lua-language-server executable after extraction

What it means

Raised after lua-language-server has been downloaded and extracted when the expected executable cannot be located in the install directory (bin/lua-language-server or bin/lua-language-server.exe). It means the archive layout differed from what the library expects or extraction failed/produced nothing usable.

Source

Thrown at src/solidlsp/language_servers/lua_ls.py:175

            download_url,
            str(install_dir),
            archive_type,
            expected_sha256=_lua_ls_sha(lua_ls_version, download_name),
            allowed_hosts=LUA_LS_ALLOWED_HOSTS,
        )

        # Make executable on Unix systems
        if system != "Windows":
            lua_ls_path = install_dir / "bin" / "lua-language-server"
            if lua_ls_path.exists():
                lua_ls_path.chmod(0o755)
                return str(lua_ls_path)
        else:
            lua_ls_path = install_dir / "bin" / "lua-language-server.exe"
            if lua_ls_path.exists():
                return str(lua_ls_path)

        raise RuntimeError("Failed to find lua-language-server executable after extraction")

    @staticmethod
    def _setup_runtime_dependency(solidlsp_settings: SolidLSPSettings) -> str:
        """
        Check if required Lua runtime dependencies are available.
        Downloads lua-language-server if not present.
        """
        lua_ls_path = LuaLanguageServer._get_lua_ls_path(solidlsp_settings)

        if not lua_ls_path:
            log.info("lua-language-server not found. Downloading...")
            lua_ls_path = LuaLanguageServer._download_lua_ls(solidlsp_settings)
            log.info("lua-language-server installed at: %s", lua_ls_path)

        return lua_ls_path

    def __init__(self, config: LanguageServerConfig, repository_root_path: str, solidlsp_settings: SolidLSPSettings):
        lua_ls_path = self._setup_runtime_dependency(solidlsp_settings)

View on GitHub (pinned to 7fcbca7e62)

Solutions

Delete install_dir under the multilspy ls_resources_dir and retry to force a clean re-download/extraction
Check the extracted directory listing; if the binary sits in a nested folder, adjust or symlink it to install_dir/bin/lua-language-server
Verify the downloaded archive integrity (file/tar -tzf) and network path to the GitHub release
Pin/inspect the lua_ls_version used; downgrade to a version whose archive layout matches the library's expectation

Example fix

// before
ls install_dir  # shows nested lua-language-server-3.x/bin/...
// after
mv install_dir/lua-language-server-3.x/* install_dir/ && rerun  # or clear cache and reinstall

Defensive patterns

Strategy: validation

Validate before calling

import pathlib
from multilspy import SyncLanguageServer  # after install attempt
install_dir = pathlib.Path("~/.multilspy/resources/lua").expanduser()
exe = install_dir / "bin" / "lua-language-server"
if not exe.exists():
    print(f"missing {exe}; wipe {install_dir} and retry download")

Try / catch

try:
    server = create_lua_server()
except RuntimeError as e:
    if "Failed to find lua-language-server executable" in str(e):
        shutil.rmtree(install_dir, ignore_errors=True)
        server = create_lua_server()  # one clean retry
    else:
        raise

Prevention

Clear cached LS resources after library or LuaLS version upgrades
Ensure adequate disk space and stable network in CI
Verify archive integrity when downloads are proxied
Check antivirus exclusions for the resources dir on Windows

When it happens

Trigger: Upstream release changed the archive's internal directory structure (e.g. nested top-level folder or renamed bin dir), the tar.gz/zip was corrupted or truncated mid-download, extraction skipped file permission bits so the file check fails, or the download URL returned an HTML error page.

Common situations: LuaLS published a new release version with a reshaped zip, flaky CI networks producing partial archives, antivirus quarantining the extracted exe on Windows, read-only or full disk causing silent extraction failure.

Related errors

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