{"record":{"id":"a821f5eb03b47b2c","repo":"oraios/serena","slug":"no-usable-compile-commands-json-at-self-repositor","errorCode":null,"errorMessage":"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\nGenerate one from the engine's \\Binaries\\DotNET\\UnrealBuildTool\\ directory:\n UnrealBuildTool.exe -mode=GenerateClangDatabase -project=\".uproject\" Editor Win64 Development -OutputDir=\"\"\nWithout a clang toolchain, append -Compiler=VisualStudio2022 to build an MSVC database instead.\n\nBuild 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.\nSee docs/03-special-guides/unreal_engine_setup_guide_for_serena.md for details.","messagePattern":"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\nGenerate one from the engine's \\\\Binaries\\\\DotNET\\\\UnrealBuildTool\\\\ directory:\n UnrealBuildTool\\.exe -mode=GenerateClangDatabase -project=\"\\.uproject\" Editor Win64 Development -OutputDir=\"\"\nWithout a clang toolchain, append -Compiler=VisualStudio2022 to build an MSVC database instead\\.\n\nBuild 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\\.\nSee docs/03-special-guides/unreal_engine_setup_guide_for_serena\\.md for details\\.","errorType":"exception","errorClass":"SolidLSPException","httpStatus":null,"severity":"error","filePath":"src/solidlsp/language_servers/clangd_language_server.py","lineNumber":120,"sourceCode":" return None\n\n @override\n def is_ignored_dirname(self, dirname: str) -> bool:\n return (\n super().is_ignored_dirname(dirname)\n or dirname == \".ccls-cache\"\n or (is_unreal_engine_project(self.repository_root_path) and dirname in UE_IGNORED_DIRNAMES)\n )\n\n def _raise_if_unreal_without_compile_db(self) -> None:\n \"\"\"Raise if this is an Unreal Engine project without a usable compilation database.\n\n clangd cannot resolve engine headers or macros without one. Non-UE projects return\n without raising, since clangd works without a database there.\n \"\"\"\n if not is_unreal_engine_project(self.repository_root_path):\n return\n raise SolidLSPException(\n f\"No usable compile_commands.json at {self.repository_root_path}, but this looks like an \"\n \"Unreal Engine project (.uproject present). clangd needs a non-empty compilation database \"\n \"to resolve engine headers and macros.\\n\\n\"\n \"Generate one from the engine's \\\\Binaries\\\\DotNET\\\\UnrealBuildTool\\\\ directory:\\n\"\n ' UnrealBuildTool.exe -mode=GenerateClangDatabase -project=\".uproject\" '\n 'Editor Win64 Development -OutputDir=\"\"\\n'\n \"Without a clang toolchain, append -Compiler=VisualStudio2022 to build an MSVC database instead.\\n\\n\"\n \"Build the editor target once first so the generated headers exist. After creating the \"\n \"database, reconnect or restart Serena's MCP so the language server re-checks for it.\\n\"\n \"See docs/03-special-guides/unreal_engine_setup_guide_for_serena.md for details.\"\n )\n\n def _prepare_compile_commands(self) -> str | None:\n \"\"\"\n Prepare clangd compilation database with absolute directory paths.\n\n Clangd requires absolute directory paths in compile_commands.json for correct\n cross-file reference finding. This method reads the compile_commands.json,","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/oraios/serena/blob/7fcbca7e62555ec2287ddb2f083caee805848ea6/src/solidlsp/language_servers/clangd_language_server.py#L102-L138","documentation":"_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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Generate compile_commands.json via UnrealBuildTool from the engine's Binaries/DotNET/UnrealBuildTool directory: UnrealBuildTool.exe -mode=GenerateClangDatabase -project=\".uproject\" Editor Win64 Development -OutputDir=\"\"","Build the editor target once first so generated headers exist before generating the database","Without a clang toolchain, append -Compiler=VisualStudio2022 to produce an MSVC database","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"],"exampleFix":"// before\n# .uproject present, no compile_commands.json -> SolidLSPException\n\"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\"\n// after\n# compile_commands.json now at project root; restart the language server","handlingStrategy":"validation","validationCode":"import glob, json, os\nis_ue = bool(glob.glob(os.path.join(root, \"*.uproject\")))\ndb = os.path.join(root, \"compile_commands.json\")\nif is_ue and (not os.path.exists(db) or os.path.getsize(db) == 0):\n print(\"Generate compile_commands.json via UnrealBuildTool -mode=GenerateClangDatabase before starting clangd\")","typeGuard":null,"tryCatchPattern":"from solidlsp import SolidLSPException\ntry:\n server = ClangdLanguageServer(...)\nexcept SolidLSPException as e:\n if \"compile_commands.json\" in str(e) and \"Unreal\" in str(e):\n raise SystemExit(\"Run UnrealBuildTool -mode=GenerateClangDatabase, build the editor target once, then restart the server\")\n raise","preventionTips":["Always build the editor target once before generating the clang database so generated headers exist","Keep compile_commands.json at the project root and regenerate after project changes","Follow docs/03-special-guides/unreal_engine_setup_guide_for_serena.md and restart the MCP connection after generating the database"],"tags":["clangd","unreal-engine","compile-commands","compilation-database","cpp"],"backgroundTag":"missing-compilation-database","analyzedSha":"7fcbca7e62555ec2287ddb2f083caee805848ea6","analyzedAt":"2026-08-29T00:04:09.619Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}