{"record":{"id":"66eb3548dcafc217","repo":"OtterMind/Chat2DB","slug":"unable-to-register-the-chat2db-preview-resource-sc","errorCode":null,"errorMessage":"Unable to register the Chat2DB preview resource scheme","messagePattern":"Unable to register the Chat2DB preview resource scheme","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"chat2db-community-server/chat2db-community-jcef/src/main/java/ai/chat2db/community/jcef/handler/biz/PreviewResourceScheme.java","lineNumber":49,"sourceCode":"    private static final String DOMAIN = \"preview\";\n    private static final DateTimeFormatter HTTP_DATE = DateTimeFormatter.RFC_1123_DATE_TIME.withZone(ZoneOffset.UTC);\n\n    private PreviewResourceScheme() {\n    }\n\n    public static void registerScheme(CefSchemeRegistrar registrar) {\n        boolean registered = registrar.addCustomScheme(\n                SCHEME,\n                true,\n                false,\n                false,\n                true,\n                true,\n                false,\n                false\n        );\n        if (!registered) {\n            throw new IllegalStateException(\"Unable to register the Chat2DB preview resource scheme\");\n        }\n    }\n\n    public static void registerFactory(CefApp cefApp) {\n        boolean registered = cefApp.registerSchemeHandlerFactory(\n                SCHEME,\n                DOMAIN,\n                (browser, frame, schemeName, request) -> new PreviewResourceHandler()\n        );\n        if (!registered) {\n            throw new IllegalStateException(\"Unable to register the Chat2DB preview resource handler\");\n        }\n    }\n\n    static String createUrl(String rootToken, String relativePath) {\n        return createUrl(rootToken, relativePath, null);\n    }\n","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/OtterMind/Chat2DB/blob/5ee1e990e73fbcae1969dc554be254fedb3ab888/chat2db-community-server/chat2db-community-jcef/src/main/java/ai/chat2db/community/jcef/handler/biz/PreviewResourceScheme.java#L31-L67","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure CefApp is initialized exactly once per process lifecycle — CEF does not support re-registering custom schemes","If re-initialization is needed, restart the JVM process rather than calling CefApp.startApp again","Check whether another module or test also calls registerScheme with the same scheme name","Verify the scheme name 'chat2db-resource' does not collide with a CEF built-in in your JCEF version"],"exampleFix":"// before: registration called unconditionally, may double-register\nPreviewResourceScheme.registerScheme(registrar);\n\n// after: guard against duplicate registration (if re-init is unavoidable)\ntry {\n    PreviewResourceScheme.registerScheme(registrar);\n} catch (IllegalStateException e) {\n    log.warn(\"Scheme already registered, skipping: {}\", e.getMessage());\n}","handlingStrategy":"validation","validationCode":"// Ensure registerScheme is called exactly once per process\nprivate static final AtomicBoolean schemeRegistered = new AtomicBoolean(false);\n\nif (schemeRegistered.compareAndSet(false, true)) {\n    PreviewResourceScheme.registerScheme(registrar);\n} else {\n    log.warn(\"Preview resource scheme already registered, skipping\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    PreviewResourceScheme.registerScheme(registrar);\n} catch (IllegalStateException e) {\n    log.warn(\"Custom scheme registration failed (may already be registered): {}\", e.getMessage());\n    // Non-fatal: scheme registration is process-lifetime in CEF\n}","preventionTips":["Initialize CefApp exactly once per JVM process — CEF does not support re-registration","If CefApp needs re-creation, restart the JVM process instead","Audit all code paths that call registerScheme to ensure there is exactly one call site"],"tags":["jcef","cef","scheme-registration","lifecycle","desktop"],"backgroundTag":null,"analyzedSha":"5ee1e990e73fbcae1969dc554be254fedb3ab888","analyzedAt":"2026-08-14T07:05:03.077Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}