OtterMind/Chat2DB · error · IllegalStateException

Unable to register the Chat2DB preview resource scheme

Error message

Unable to register the Chat2DB preview resource scheme

What it means

Thrown by PreviewResourceScheme.registerScheme() when CefSchemeRegistrar.addCustomScheme() returns false. CEF rejects custom scheme registration if the scheme name is already registered, if the name violates CEF naming rules, or if the call happens outside the onRegisterCustomSchemes lifecycle callback. This method is called from MainJFrame.onRegisterCustomSchemes (line 557), so the lifecycle timing is correct under normal startup — a false return most commonly means a duplicate registration attempt.

Source

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

    private static final String DOMAIN = "preview";
    private static final DateTimeFormatter HTTP_DATE = DateTimeFormatter.RFC_1123_DATE_TIME.withZone(ZoneOffset.UTC);

    private PreviewResourceScheme() {
    }

    public static void registerScheme(CefSchemeRegistrar registrar) {
        boolean registered = registrar.addCustomScheme(
                SCHEME,
                true,
                false,
                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);
    }

View on GitHub (pinned to 5ee1e990e7)

Solutions

1. Ensure CefApp is initialized exactly once per process lifecycle — CEF does not support re-registering custom schemes
2. If re-initialization is needed, restart the JVM process rather than calling CefApp.startApp again
3. Check whether another module or test also calls registerScheme with the same scheme name
4. Verify the scheme name 'chat2db-resource' does not collide with a CEF built-in in your JCEF version

Example fix

// before: registration called unconditionally, may double-register
PreviewResourceScheme.registerScheme(registrar);

// after: guard against duplicate registration (if re-init is unavoidable)
try {
    PreviewResourceScheme.registerScheme(registrar);
} catch (IllegalStateException e) {
    log.warn("Scheme already registered, skipping: {}", e.getMessage());
}

// Ensure registerScheme is called exactly once per process
private static final AtomicBoolean schemeRegistered = new AtomicBoolean(false);

if (schemeRegistered.compareAndSet(false, true)) {
    PreviewResourceScheme.registerScheme(registrar);
} else {
    log.warn("Preview resource scheme already registered, skipping");
}

try {
    PreviewResourceScheme.registerScheme(registrar);
} catch (IllegalStateException e) {
    log.warn("Custom scheme registration failed (may already be registered): {}", e.getMessage());
    // Non-fatal: scheme registration is process-lifetime in CEF
}

When it happens

Trigger: addCustomScheme returns false when: the 'chat2db-resource' scheme was already registered (e.g., a CefApp restart or re-initialization within the same process), the scheme name collides with a CEF built-in, or the registrar is in a state that no longer accepts scheme additions.

Common situations: CefApp being re-initialized without a full process restart (CEF retains the scheme registration); a plugin or test harness that also registers the same scheme; a CEF version upgrade that changed scheme registration semantics or added 'chat2db-resource' as a reserved name.

Related errors

• Unable to register the Chat2DB preview resource handler
• 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/66eb3548dcafc217. Report an issue: GitHub.