OtterMind/Chat2DB · error · IllegalStateException

Unable to register the Chat2DB preview resource handler

Error message

Unable to register the Chat2DB preview resource handler

What it means

Thrown by PreviewResourceScheme.registerFactory() when CefApp.registerSchemeHandlerFactory() returns false for the 'chat2db-resource' scheme on the 'preview' domain. CEF rejects factory registration if the scheme+domain combination already has a handler, or if CefApp is past the initialization window that accepts factory registration. Called from onContextInitialized (MainJFrame line 547).

Source

Thrown at chat2db-community-server/chat2db-community-jcef/src/main/java/ai/chat2db/community/jcef/handler/biz/PreviewResourceScheme.java:60

                false,
                true,
                true,
                false,
                false
        );
        if (!registered) {
            throw new IllegalStateException("Unable to register the Chat2DB preview resource scheme");
        }
    }

    public static void registerFactory(CefApp cefApp) {
        boolean registered = cefApp.registerSchemeHandlerFactory(
                SCHEME,
                DOMAIN,
                (browser, frame, schemeName, request) -> new PreviewResourceHandler()
        );
        if (!registered) {
            throw new IllegalStateException("Unable to register the Chat2DB preview resource handler");
        }
    }

    static String createUrl(String rootToken, String relativePath) {
        return createUrl(rootToken, relativePath, null);
    }

    static String createUrl(String rootToken, String relativePath, String version) {
        String encodedPath = Base64.getUrlEncoder().withoutPadding().encodeToString(
                (relativePath == null ? "" : relativePath).getBytes(StandardCharsets.UTF_8)
        );
        String url = SCHEME + "://" + DOMAIN + "/" + rootToken + "/" + encodedPath;
        return version == null || version.isBlank()
                ? url
                : url + "?v=" + URLEncoder.encode(version, StandardCharsets.UTF_8);
    }

    static ResourceRequest resolveRequest(String url, String method, String rangeHeader, String ifNoneMatch,

View on GitHub (pinned to 5ee1e990e7)

Solutions

1. Ensure registerFactory is called exactly once per CefApp instance, inside onContextInitialized
2. If CefApp is re-created, restart the JVM process rather than reusing the same process
3. Search for any other call site that registers a handler for 'chat2db-resource' on domain 'preview'
4. Verify onContextInitialized is not invoked more than once due to a CEF callback quirk

Example fix

// before: factory registration may fire on re-init
PreviewResourceScheme.registerFactory(cefApp_);

// after: idempotent guard
private static volatile boolean factoryRegistered = false;
if (!factoryRegistered) {
    PreviewResourceScheme.registerFactory(cefApp_);
    factoryRegistered = true;
}

// Ensure registerFactory is called exactly once per CefApp instance
private static final AtomicBoolean factoryRegistered = new AtomicBoolean(false);

if (factoryRegistered.compareAndSet(false, true)) {
    PreviewResourceScheme.registerFactory(cefApp_);
} else {
    log.warn("Preview resource factory already registered, skipping");
}

try {
    PreviewResourceScheme.registerFactory(cefApp_);
} catch (IllegalStateException e) {
    log.warn("Scheme handler factory registration failed: {}", e.getMessage());
}

When it happens

Trigger: registerSchemeHandlerFactory returns false when a handler is already registered for the same scheme and domain, or when CefApp's context is not in the state that accepts new factory registrations (e.g., called after the browser was already created).

Common situations: CefApp re-initialization in the same process; a duplicate registerFactory call from a test or plugin; the scheme handler was registered in a previous context that was not fully torn down; JCEF version change affecting factory registration timing.

Related errors

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

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