oraios/serena · error · SolidLSPException

No usable compile_commands.json at {self.repository_root_pat

Error message

No usable compile_commands.json at {self.repository_root_path}, but this looks like an Unreal Engine project (.uproject present). clangd needs a non-empty compilation database to resolve engine headers and macros.

Generate one from the engine's <Engine>\Binaries\DotNET\UnrealBuildTool\ directory:
  UnrealBuildTool.exe -mode=GenerateClangDatabase -project="<Proj>.uproject" <Proj>Editor Win64 Development -OutputDir="<projectDir>"
Without a clang toolchain, append -Compiler=VisualStudio2022 to build an MSVC database instead.

Build the editor target once first so the generated headers exist. After creating the database, reconnect or restart Serena's MCP so the language server re-checks for it.
See docs/03-special-guides/unreal_engine_setup_guide_for_serena.md for details.

What it means

_raise_if_unreal_without_compile_db raises SolidLSPException when the project is detected as Unreal Engine (a .uproject is present) but no usable compile_commands.json exists at the repository root. clangd cannot resolve engine headers and macros without a non-empty compilation database, so the library fails fast with setup instructions instead of a silently broken language server.

Source

Thrown at src/solidlsp/language_servers/clangd_language_server.py:120

            return None

    @override
    def is_ignored_dirname(self, dirname: str) -> bool:
        return (
            super().is_ignored_dirname(dirname)
            or dirname == ".ccls-cache"
            or (is_unreal_engine_project(self.repository_root_path) and dirname in UE_IGNORED_DIRNAMES)
        )

    def _raise_if_unreal_without_compile_db(self) -> None:
        """Raise if this is an Unreal Engine project without a usable compilation database.

        clangd cannot resolve engine headers or macros without one. Non-UE projects return
        without raising, since clangd works without a database there.
        """
        if not is_unreal_engine_project(self.repository_root_path):
            return
        raise SolidLSPException(
            f"No usable compile_commands.json at {self.repository_root_path}, but this looks like an "
            "Unreal Engine project (.uproject present). clangd needs a non-empty compilation database "
            "to resolve engine headers and macros.\n\n"
            "Generate one from the engine's <Engine>\\Binaries\\DotNET\\UnrealBuildTool\\ directory:\n"
            '  UnrealBuildTool.exe -mode=GenerateClangDatabase -project="<Proj>.uproject" '
            '<Proj>Editor Win64 Development -OutputDir="<projectDir>"\n'
            "Without a clang toolchain, append -Compiler=VisualStudio2022 to build an MSVC database instead.\n\n"
            "Build the editor target once first so the generated headers exist. After creating the "
            "database, reconnect or restart Serena's MCP so the language server re-checks for it.\n"
            "See docs/03-special-guides/unreal_engine_setup_guide_for_serena.md for details."
        )

    def _prepare_compile_commands(self) -> str | None:
        """
        Prepare clangd compilation database with absolute directory paths.

        Clangd requires absolute directory paths in compile_commands.json for correct
        cross-file reference finding. This method reads the compile_commands.json,

View on GitHub (pinned to 7fcbca7e62)

Solutions

  1. Generate compile_commands.json via UnrealBuildTool from the engine's Binaries/DotNET/UnrealBuildTool directory: UnrealBuildTool.exe -mode=GenerateClangDatabase -project="<Proj>.uproject" <Proj>Editor Win64 Development -OutputDir="<projectDir>"
  2. Build the editor target once first so generated headers exist before generating the database
  3. Without a clang toolchain, append -Compiler=VisualStudio2022 to produce an MSVC database
  4. After creating the database, reconnect or restart Serena's MCP so the language server re-checks for it; see docs/03-special-guides/unreal_engine_setup_guide_for_serena.md

Example fix

// before
# .uproject present, no compile_commands.json -> SolidLSPException
"C:\Program Files\Epic Games\UE_5.3\Engine\Binaries\DotNET\UnrealBuildTool\UnrealBuildTool.exe" -mode=GenerateClangDatabase -project="MyGame.uproject" MyGameEditor Win64 Development -OutputDir="C:\src\MyGame"
// after
# compile_commands.json now at project root; restart the language server
Defensive patterns

Strategy: validation

Validate before calling

import glob, json, os
is_ue = bool(glob.glob(os.path.join(root, "*.uproject")))
db = os.path.join(root, "compile_commands.json")
if is_ue and (not os.path.exists(db) or os.path.getsize(db) == 0):
    print("Generate compile_commands.json via UnrealBuildTool -mode=GenerateClangDatabase before starting clangd")

Try / catch

from solidlsp import SolidLSPException
try:
    server = ClangdLanguageServer(...)
except SolidLSPException as e:
    if "compile_commands.json" in str(e) and "Unreal" in str(e):
        raise SystemExit("Run UnrealBuildTool -mode=GenerateClangDatabase, build the editor target once, then restart the server")
    raise

Prevention

When it happens

Trigger: Starting the clangd language server on an Unreal Engine project directory containing a .uproject file where compile_commands.json is missing, empty, or unusable at repository_root_path (checked in _prepare_compile_commands -> _raise_if_unreal_without_compile_db).

Common situations: Freshly cloned UE project where the editor target has never been built; user generated the clang database with UnrealBuildTool into a different directory; database generated before building the editor target so generated headers are missing; non-UE-style build setup missing the database.

Related errors

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