{"record":{"id":"9f1edddd1c4fc8cc","repo":"OtterMind/Chat2DB","slug":"failed-to-load-frontend-files","errorCode":null,"errorMessage":"Failed to load frontend files","messagePattern":"Failed to load frontend files","errorType":"exception","errorClass":"BusinessException","httpStatus":null,"severity":"critical","filePath":"chat2db-community-server/chat2db-community-jcef/src/main/java/ai/chat2db/community/jcef/frame/MainJFrame.java","lineNumber":731,"sourceCode":"        log.error(\"Error processing request [action: {}]: {}\", action, e.getMessage(), e);\n        ResponseBuilder.buildSuccess(\n                JcefServerBridgeRegistry.getBridge().error(e, wsMessage),\n                callback\n        );\n    }\n    private void initializeBrowserAndUI() {\n        log.info(\"4. Starting CefBrowser and UI component creation...\");\n        String indexHtmlFile;\n        if (Boolean.getBoolean(WEB_FRONTEND_PROPERTY)) {\n            indexHtmlFile = WEB_FRONTEND_URL;\n            log.info(\"Using Community Web frontend for JCEF development: {}\", indexHtmlFile);\n        } else {\n            String currentJarPath = OSOperateUtil.getCurrentJarPath();\n            try {\n                Path indexHtmlPath = Paths.get(currentJarPath, \"dist\", \"index.html\").toAbsolutePath().normalize();\n                if (!Files.isRegularFile(indexHtmlPath)) {\n                    log.error(\"JCEF index file not found: {}\", indexHtmlPath);\n                    throw new BusinessException(\"Failed to load frontend files\");\n                }\n                indexHtmlFile = indexHtmlPath.toUri().toURL().toString();\n                log.info(\"Resolved JCEF index file: {}\", indexHtmlFile);\n            } catch (MalformedURLException e) {\n                log.error(e.getMessage(), e);\n                throw new BusinessException(\"Failed to load frontend files\");\n            }\n        }\n        this.browser_ = this.client_.createBrowser(indexHtmlFile, CefRendering.DEFAULT, false);\n        this.browserUI_ = browser_.getUIComponent();\n        this.browserUI_.addMouseListener(new MouseAdapter() {\n            @Override\n            public void mouseEntered(MouseEvent e) {\n                browser_.sendMouseEvent(e);\n            }\n            @Override\n            public void mousePressed(MouseEvent e) {\n                ensureBrowserFocusIfNeeded();","sourceCodeStart":713,"sourceCodeEnd":749,"githubUrl":"https://github.com/OtterMind/Chat2DB/blob/5ee1e990e73fbcae1969dc554be254fedb3ab888/chat2db-community-server/chat2db-community-jcef/src/main/java/ai/chat2db/community/jcef/frame/MainJFrame.java#L713-L749","documentation":"Thrown by initializeBrowserAndUI() during JCEF desktop startup when the frontend entry point <jarDir>/dist/index.html does not exist as a regular file. The method resolves the path via OSOperateUtil.getCurrentJarPath(), checks Files.isRegularFile, and aborts with BusinessException if the file is absent. This is a packaging or working-directory failure, not a transient runtime error — the JCEF embedded browser has no page to render, so the application window loads blank.","triggerScenarios":"Launching the Community desktop jar without the assembled dist/ folder alongside it. Specifically: running java -jar target/chat2db-community.jar directly after mvn package without the frontend build output, or when OSOperateUtil.getCurrentJarPath() returns a directory that does not contain a dist/index.html file.","commonSituations":"Running the raw target jar before script/package/package-community-jcef.sh prepare copies the frontend dist/ output; a CI build that skipped frontend assembly (build:web:community); moving the jar out of its staging directory without dist/; a partial prepare that built the backend but failed silently on the frontend step.","solutions":["Run script/package/package-community-jcef.sh <version> prepare to assemble dist/ alongside the jar before launch","During frontend development, pass -Dchat2db.jcef.web-frontend=true so the browser loads http://127.0.0.1:8889/ instead of the filesystem","Check the 'JCEF index file not found' log line for the exact resolved path and verify dist/index.html exists at that location","Verify OSOperateUtil.getCurrentJarPath() returns the expected directory — if the jar is run from an unexpected cwd the path may resolve incorrectly"],"exampleFix":"// before: jar launched without assembled frontend\njava -jar target/chat2db-community.jar\n\n// after: assemble dist/ first, or use dev web frontend\nscript/package/package-community-jcef.sh 0.0.0-local prepare\njava -Dchat2db.runtime.mode=community -jar chat2db-community.jar\n\n// or for live frontend development:\njava -Dchat2db.jcef.web-frontend=true -jar target/chat2db-community.jar","handlingStrategy":"validation","validationCode":"// Before launching the desktop jar, verify dist/index.html exists\nString jarDir = OSOperateUtil.getCurrentJarPath();\nPath indexHtml = Paths.get(jarDir, \"dist\", \"index.html\").toAbsolutePath().normalize();\nif (!Files.isRegularFile(indexHtml)) {\n    throw new IllegalStateException(\n        \"Frontend dist/index.html not found at \" + indexHtml\n        + \". Run package-community-jcef.sh prepare, or set -Dchat2db.jcef.web-frontend=true for dev.\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always run the packaging prepare step before launching the desktop jar","Use -Dchat2db.jcef.web-frontend=true during frontend development to bypass filesystem resolution","Log the resolved index path early in startup so missing dist/ is immediately diagnosable","Verify the prepare step's frontend build completed successfully before launching"],"tags":["jcef","frontend","packaging","startup","desktop"],"backgroundTag":null,"analyzedSha":"5ee1e990e73fbcae1969dc554be254fedb3ab888","analyzedAt":"2026-08-14T07:05:03.077Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}