Common issues
Characters appear as symbols in the browser
When displaying documents in a browser, they must be encoded in UTF-8 to ensure characters are rendered correctly. If the source file uses a different encoding, unexpected symbols may appear in place of the intended text.
Browser Launch Crashes
-
For systems using Wayland, see the Wayland support documentation.
-
If you’ve enabled the
chromium.multi_threaded_message_loop=true
property, refer to the Multi-threaded documentation.
Applies to Linux and SWT environments. |
Blocking on SWT Browser JS Events
Invoking org.eclipse.swt.browser.Browser.evaluate
after starting the Equo Chromium browser may block the main thread for several seconds and result in an evaluation failure stack trace.
This issue arises because SWT and Equo Chromium share the same UI thread, which can lead to deadlocks.
To prevent this, enable Multi-threaded mode.
Applies to Linux and SWT environments. |
Custom Font Rendering Issues
Custom fonts not bundled with the operating system may not render correctly in the Equo browser unless installed locally.
To avoid requiring local installation, embed fonts using:
@font-face {
font-family: 'Some Custom Font';
src: url('someCustomFont.woff2') format('woff2');
}
Or link fonts via the HTML <head>
tag:
<link href="https://fonts.googleapis.com/css?family=Some+Custom+Font" rel="stylesheet">
To verify font rendering, open browser DevTools and toggle the font property. A visible text change indicates that the font is active.


No visible change means the font is unavailable on the system.
Webcam Not Working
Webcam support is disabled by default. Enable it with:
-Dchromium.args="--enable-media-stream;--use-fake-ui-for-media-stream"
Some features require the Equo Chromium "media" build. |
Visual Glitches in Browser UI
Older GPUs may cause flickering, black borders, or other rendering issues. To resolve this, disable GPU acceleration:
-Dchromium.args="--disable-gpu;--disable-gpu-compositing"
BrowserFunction Fails on Local Files
When loading local files, BrowserFunction
may not execute due to Chromium security restrictions. Override this behavior with:
-Dchromium.args="--disable-web-security"
Performance Issues with Large Content in setText
Using setText
for large resources may cause delays. For better performance, enable:
-Dchromium.setTextAsUrl=file:
This serves content via temporary files. Be aware of security trade-offs. See the "setText" Method’s Performance page.
For a more secure and performant alternative, consider using Middleware. It avoids temporary files and improves efficiency. Contact our support team for help. |
Customizing Browser Theme
The browser follows the system theme by default. To force dark mode:
-Dchromium.args="--force-dark-mode"
To override the system theme with light mode:
-Dchromium.args="--ignore-dark-mode"
--ignore-dark-mode is deprecated as of Chromium 124.0.2. Use --force-light-mode instead.
|
Blank Browser in Docker
In Docker environments, the browser may appear blank without additional flags. Use:
-Dchromium.args=--disable-gpu;--disable-gpu-compositing;--disable-dev-shm-usage
Cache Path Already in Use
Starting with Chromium 120, unique cache paths are mandatory per instance to avoid corruption and improve security.
In Eclipse-based apps, default paths are now scoped to each workspace.
Enforced as of version 128.0.5 |
If specifying -Dchromium.cache_path
, ensure each browser instance uses a unique path. Shared paths are unsupported.