oraios/serena · error · FileNotFoundError

qmlls (QML language server) is not installed or not in PATH.

Error message

qmlls (QML language server) is not installed or not in PATH.
Please install Qt 6 and ensure 'qmlls' (or 'qmlls6') is available on your PATH.
See: https://doc.qt.io/qt-6/qtqml-tool-qmlls.html

What it means

The QML language server used here is qmlls, which ships with Qt 6; the library does not download it. The dependency provider looks for 'qmlls6' then 'qmlls' via shutil.which, and raises this FileNotFoundError if neither is on PATH. Note the lookup only checks PATH — the ls_path override in ls_specific_settings.qml is honored by the generic provider layer.

Source

Thrown at src/solidlsp/language_servers/qml_language_server.py:49

    def __init__(self, config: LanguageServerConfig, repository_root_path: str, solidlsp_settings: SolidLSPSettings):
        super().__init__(config, repository_root_path, None, "qml", solidlsp_settings)

    def _create_dependency_provider(self) -> LanguageServerDependencyProvider:
        return self.DependencyProvider(self._custom_settings, self._ls_resources_dir)

    class DependencyProvider(LanguageServerDependencyProviderSinglePath):
        def _get_or_install_core_dependency(self) -> str:
            """
            Discover the qmlls executable on PATH.

            Tries ``qmlls6`` first (Qt 6+), then falls back to ``qmlls``.

            :return: path to the qmlls executable
            :raises FileNotFoundError: if qmlls is neither on PATH nor provided via ``ls_path``
            """
            qmlls_binary = shutil.which("qmlls6") or shutil.which("qmlls")
            if qmlls_binary is None:
                raise FileNotFoundError(
                    "qmlls (QML language server) is not installed or not in PATH.\n"
                    "Please install Qt 6 and ensure 'qmlls' (or 'qmlls6') is available on your PATH.\n"
                    "See: https://doc.qt.io/qt-6/qtqml-tool-qmlls.html"
                )
            return qmlls_binary

        def _create_launch_command(self, core_path: str) -> list[str]:
            # qmlls communicates via stdio by default; no extra flags are required.
            return [core_path]

    def _create_base_initialize_params(self) -> dict:
        """
        Return the language-specific initialize params for the QML language server.

        ``processId``, ``rootPath``, ``rootUri`` and ``workspaceFolders`` are populated by the
        default ``InitializeParamsBuilder`` and must not be set here.
        """
        initialize_params = {

View on GitHub (pinned to 7fcbca7e62)

Solutions

Install Qt 6 tooling: e.g. apt install qt6-declarative-dev (Debian/Ubuntu), dnf install qt6-qtdeclarative-devel (Fedora), or brew install qt.
Add the Qt bin directory containing qmlls to PATH, e.g. export PATH="$HOME/Qt/6.6.0/gcc_64/bin:$PATH".
If qmlls is installed elsewhere, set ls_specific_settings['qml']['ls_path'] to its full path.
Verify with `which qmlls6 || which qmlls` before creating the server; a plain 'qmlls' on PATH that belongs to Qt 5 won't help — you need a Qt 6 build.

Example fix

// before (Serena config, qmlls outside PATH)
"ls_specific_settings": { "qml": {} }
// after
"ls_specific_settings": { "qml": { "ls_path": "/home/user/Qt/6.6.0/gcc_64/bin/qmlls" } }

Defensive patterns

Strategy: validation

Validate before calling

import shutil
cfg = serena_settings.get('ls_specific_settings', {}).get('qml', {})
if not cfg.get('ls_path') and not (shutil.which('qmlls6') or shutil.which('qmlls')):
    raise SystemExit(
        "qmlls not found. Install Qt 6 (e.g. 'apt install qt6-declarative-dev' or 'brew install qt') "
        "and add its bin dir to PATH, or set ls_specific_settings['qml']['ls_path']."
    )

Try / catch

try:
    server = SolidLanguageServer.create('qml', repo_root, settings)
except FileNotFoundError as e:
    if 'qmlls' in str(e) and 'not installed' in str(e):
        raise EnvironmentError(
            'qmlls missing: install Qt 6 tools (https://doc.qt.io/qt-6/qtqml-tool-qmlls.html) '
            'or set ls_specific_settings["qml"]["ls_path"] to the qmlls binary.'
        ) from e
    raise

Prevention

Verify `which qmlls6 || which qmlls` succeeds in the exact environment (venv/CI/WSL) that launches Serena.
Install the Qt tools package, not just libraries — qmlls ships with Qt 6 tool components.
Add your Qt install's bin dir (e.g. ~/Qt/<version>/<kit>/bin) to PATH in shell startup files.
For non-standard installs, always set ls_specific_settings['qml']['ls_path'].

When it happens

Trigger: Creating the QML language server on a machine without Qt 6 tools installed, with qmlls installed under a name/location not on PATH (e.g. ~/Qt/Tools/QtDesignStudio/bin or a versioned dir like Qt/6.6/gcc_64/bin), or in a minimal Docker/CI image with no Qt toolchain.

Common situations: Qt installed via the online installer without the 'Qt Tools'/qml components; qmlls present but its bin dir not exported to PATH in the current shell/venv; using distro packages that ship qmlls as a separate package (e.g. qt6-qtdeclarative-devel / qt6-declarative-tools); WSL or container without Qt.

Related errors

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