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.

Correct font rendering: "Some Custom Font"

Fallback rendering without the custom font

No visible change means the font is unavailable on the system.

Webcam Not Working

Webcam support is disabled by default. You can enable it with:

-Dchromium.args="--enable-media-stream;--use-fake-ui-for-media-stream"

Some features will 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 Equo Chromium version 124.0.2. Use --force-light-mode instead.

Blank Browser in Docker

In Docker environments, the browser may appear blank without additional flags. To fix it use:

-Dchromium.args=--disable-gpu;--disable-gpu-compositing;--disable-dev-shm-usage

Cache Path Already in Use

Starting with Chromium version 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 Equo Chromium version 128.0.5

If specifying -Dchromium.cache_path, ensure each browser instance uses a unique path. Shared paths are unsupported.