OtterMind/Chat2DB · critical · BusinessException

Failed to load frontend files

Error message

Failed to load frontend files

What it means

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.

Source

Thrown at chat2db-community-server/chat2db-community-jcef/src/main/java/ai/chat2db/community/jcef/frame/MainJFrame.java:731

        log.error("Error processing request [action: {}]: {}", action, e.getMessage(), e);
        ResponseBuilder.buildSuccess(
                JcefServerBridgeRegistry.getBridge().error(e, wsMessage),
                callback
        );
    }
    private void initializeBrowserAndUI() {
        log.info("4. Starting CefBrowser and UI component creation...");
        String indexHtmlFile;
        if (Boolean.getBoolean(WEB_FRONTEND_PROPERTY)) {
            indexHtmlFile = WEB_FRONTEND_URL;
            log.info("Using Community Web frontend for JCEF development: {}", indexHtmlFile);
        } else {
            String currentJarPath = OSOperateUtil.getCurrentJarPath();
            try {
                Path indexHtmlPath = Paths.get(currentJarPath, "dist", "index.html").toAbsolutePath().normalize();
                if (!Files.isRegularFile(indexHtmlPath)) {
                    log.error("JCEF index file not found: {}", indexHtmlPath);
                    throw new BusinessException("Failed to load frontend files");
                }
                indexHtmlFile = indexHtmlPath.toUri().toURL().toString();
                log.info("Resolved JCEF index file: {}", indexHtmlFile);
            } catch (MalformedURLException e) {
                log.error(e.getMessage(), e);
                throw new BusinessException("Failed to load frontend files");
            }
        }
        this.browser_ = this.client_.createBrowser(indexHtmlFile, CefRendering.DEFAULT, false);
        this.browserUI_ = browser_.getUIComponent();
        this.browserUI_.addMouseListener(new MouseAdapter() {
            @Override
            public void mouseEntered(MouseEvent e) {
                browser_.sendMouseEvent(e);
            }
            @Override
            public void mousePressed(MouseEvent e) {
                ensureBrowserFocusIfNeeded();

View on GitHub (pinned to 5ee1e990e7)

Solutions

1. Run script/package/package-community-jcef.sh <version> prepare to assemble dist/ alongside the jar before launch
2. During frontend development, pass -Dchat2db.jcef.web-frontend=true so the browser loads http://127.0.0.1:8889/ instead of the filesystem
3. Check the 'JCEF index file not found' log line for the exact resolved path and verify dist/index.html exists at that location
4. Verify OSOperateUtil.getCurrentJarPath() returns the expected directory — if the jar is run from an unexpected cwd the path may resolve incorrectly

Example fix

// before: jar launched without assembled frontend
java -jar target/chat2db-community.jar

// after: assemble dist/ first, or use dev web frontend
script/package/package-community-jcef.sh 0.0.0-local prepare
java -Dchat2db.runtime.mode=community -jar chat2db-community.jar

// or for live frontend development:
java -Dchat2db.jcef.web-frontend=true -jar target/chat2db-community.jar

// Before launching the desktop jar, verify dist/index.html exists
String jarDir = OSOperateUtil.getCurrentJarPath();
Path indexHtml = Paths.get(jarDir, "dist", "index.html").toAbsolutePath().normalize();
if (!Files.isRegularFile(indexHtml)) {
    throw new IllegalStateException(
        "Frontend dist/index.html not found at " + indexHtml
        + ". Run package-community-jcef.sh prepare, or set -Dchat2db.jcef.web-frontend=true for dev.");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Missing local file path
• Failed to update local file
• e.getMessage()
• Unable to register the Chat2DB preview resource scheme
• Unable to register the Chat2DB preview resource handler

AI-assisted analysis of OtterMind/Chat2DB@5ee1e990e7 (2026-08-14). Data as JSON: /api/errors/9f1edddd1c4fc8cc. Report an issue: GitHub.