Skip to content

GTK/WebKit

Linux GTK/WebKit "Nothing Renders" Checklist

Operational Diagnostic Guide

Operational Diag Guide⚓︎

  • An Operational Diagnostic Guide for troubleshooting instances where GTK/WebKit-based applications (e.g., Remarkable, Devhelp, Yelp, GNOME Help) launch successfully but render a completely blank content pane.

⚡ Quick Triage (The 2-Minute Version)⚓︎

Quick Triage

  • Before executing the full diagnostic tree, run these four commands to immediately isolate the root cause.
pkill WebKitWebProcess

fc-match monospace

coredumpctl list WebKitWebProcess | tail

LIBGL_ALWAYS_SOFTWARE=1 devhelp

🔍 Immediate Indicator Matrix⚓︎

Diagnostic Signal Identified Subsystem Immediate Action
pkill resolves issue Stale Render Process Document incident; restart application.
fc-match fails/hangs Font Config Subsystem Proceed directly to Step 5 (Cache Reset).
coredumpctl shows fresh logs WebKit Core Crash Proceed to Step 2 (Crash Analysis).
LIBGL variable resolves issue GPU / Mesa Driver Proceed to Step 6 (Hardware Isolation).

Core Diagnostic Rule

If multiple WebKitGTK applications suddenly render blank content simultaneously, suspect the shared WebKit rendering stack before troubleshooting the individual applications.

🎮 Cross-Hardware Graphics Triage⚓︎

Cross-Hardware Graphics Triage

When an application works under LIBGL_ALWAYS_SOFTWARE=1, the issue lies within your hardware acceleration pipeline. Select your active GPU architecture below to run targeted environment overrides before resorting to full software fallback.

Because you are running an AMD Radeon RX 580 via the open-source Mesa drivers, rendering issues are often caused by WebKit fighting with hardware acceleration, WebGL, or driver compilation layers.

  • Disable GPU Sandboxing (WebKit Flag)
    devhelp --disable-gpu-sandbox

    Use Case: WebKit's security sandbox often clashes with AMD driver memory allocation. If this works, the issue is sandboxing, not your GPU.
  • Bypass Driver Shaders (Mesa Toggles)
    R600_DEBUG=nocall devhelp
# OR (For newer Vulkan-based WebKit paths)
RADV_DEBUG=nocache devhelp

    Use Case: Disables specific hardware-level optimization steps in the AMD driver to see if a driver bug is misdrawing the app window.
  • Disable Compositing Mode
    WEBKIT_DISABLE_COMPOSITING_MODE=1 devhelp

    Use Case: Forces WebKit to draw the window layout using standard rendering instead of hardware acceleration, bypassing deep driver layers entirely.

The proprietary Nvidia driver stack utilizes a completely different rendering path than Mesa. WebKit failures here usually relate to GLX contexts, thread management, or power-saving states.

  • Force Legacy GLX Indirect Rendering
    __GLX_FORCE_VENDOR_LIBRARY_0=1 devhelp

    Use Case: Bypasses Nvidia's direct rendering infrastructure if there is a context mismatch between GTK and the display server.
  • Disable Threaded Optimizations
    __GL_THREADED_OPTIMUS=0 devhelp

    Use Case: Resolves timing-related race conditions where WebKit threads collapse while communicating with the Nvidia binary driver.
  • Force WebKit WebGL Disabling
    WEBKIT_DISABLE_DMABUF_RENDERER=1 devhelp

    Use Case: Fixes blank screens on Nvidia setups caused by broken DMA-BUF memory sharing protocols between the GPU and WebKit processes.

Intel graphics rely heavily on the modern iris driver within Mesa. Under production stress, it can experience severe rendering sync drops or memory caching faults.

  • Force Older Intel Driver Generation
    MESA_LOADER_DRIVER_OVERRIDE=i965 devhelp

    Use Case: Forces the system to fall back from the modern Iris driver to the mature, stable legacy i965 driver path.
  • Disable Performance Cache Compilations
    INTEL_DEBUG=nocache devhelp

    Use Case: Instructs the Intel driver to bypass the internal shader cache, clearing up pipeline errors caused by corrupted system shader trees.

📋 Comprehensive Diagnostic Steps⚓︎

Step 0 — Isolate Scope⚓︎

Isolate Scope

Determine if the rendering failure is isolated or system-wide by testing at least two independent WebKit applications (e.g., remarkable and devhelp).

Run the following test suite in your terminal:

remarkable & devhelp &

Observation Diagnostic Deductible Operational Focus
One application broken App-Specific Configuration Error Check local app configs, dotfiles, or extensions.
Both applications broken Shared Stack Corruption Target shared libraries (WebKit, GTK, Fonts, GPU).

Step 1 — Check for WebKit Crashes⚓︎

Check for Webkit Crashes

Inspect the system core dump manager to verify if the underlying WebKit process is actively terminating.

coredumpctl list WebKitWebProcess

Analysis of Outputs

If fresh entries are populated in the list, extract the specific crash metadata using the Process ID (PID):

coredumpctl info <PID>

* Critical Signal to Look For: Signal: 6 (ABRT) or any explicit WebKitWebProcess failure tracking.
* Verdict: If present, the WebKit engine itself is unstable. Proceed to package integrity validation.

Step 2 — Trace Terminal Standard Outputs⚓︎

Trace Terminal Standard Outputs

Launch the affected application directly from an active terminal session to capture real-time stdout and stderr diagnostic streams.

devhelp
# OR
remarkable

Error Signature Branching

  • Signature: Segmentation fault
    👉 Verdict: Memory corruption or binary incompatibility. Skip rendering checks; review system memory or package versions.
  • Signature: References to GLib, WebKit, or JavaScriptCore
    👉 Verdict: Broken rendering stack. Proceed with the checklist sequentially.

Step 3 — Terminate Stale WebKit Renderers⚓︎

Terminate Stale WebKit Renderers

Stale background rendering processes can lock shared resources and prevent new instances from drawing GUI surfaces.

pkill WebKitWebProcess

Validation

Relaunch the target application. If the interface renders correctly, a stale or orphaned renderer state was blocking execution.

Step 4 — Verify Font Subsystem Integrity⚓︎

Verify Font Subsystem Integrity

A corrupted, missing, or hanging system font configuration can completely block text-heavy WebKit canvas initialization.

fc-match monospace

fc-list | head

Output Evaluation

  • Positive Indicators: Clean, instant stdout mapping to local fonts (e.g., Noto Sans, DejaVu).
  • Negative Indicators: Missing output, explicitly logged errors, or a terminal hang. Proceed immediately to Step 5.

Step 5 — Rebuild Font Subsystem Caches⚓︎

Rebuild Font Subsystem Caches

Force a complete purge and regeneration of the font configuration binaries. Execute this if Step 4 yielded any anomalies.

rm -rf ~/.cache/fontconfig

fc-cache -rv

Post-Execution Action

Relaunch your WebKit applications to verify if the fresh font map resolves the rendering block.

Step 6 — Isolate GPU and Mesa Driver Conflicts⚓︎

Isolate GPU and Mesa Driver Conflicts

Determine if hardware acceleration or the graphics driver stack is causing rendering failures by forcing a pure software rendering fallback.

LIBGL_ALWAYS_SOFTWARE=1 devhelp
# OR
LIBGL_ALWAYS_SOFTWARE=1 remarkable

Deductible Outcomes

  • Resolved: A direct incompatibility exists between the user-space driver, kernel GPU module, and WebKit's hardware pipeline. Move to the Cross-Hardware Graphics Triage section to find an architectural workaround.
  • Unchanged: The hardware acceleration pipeline is highly unlikely to be the root cause.

Step 7 — Validate Package Integrity⚓︎

Validate Package Integrity

Verify that the shared WebKit libraries and components are complete, uncorrupted, and synchronized via pacman.

Verify versions

pacman -Q webkit2gtk-4.1 javascriptcoregtk-4.1

Verify file hashes and permissions

pacman -Qkk webkit2gtk-4.1

Package Discrepancies

Look closely for warnings concerning Missing files, Modified files, or Partial upgrades. If any are found, force-reinstall the packages:

sudo pacman -S webkit2gtk-4.1 javascriptcoregtk-4.1

Step 8 — Query System Logs for Component Failures⚓︎

Query System Logs for Component Failures

Filter user and system journals specifically for WebKit engine events generated during the current boot cycle.

journalctl -b --user | grep -i webkit

journalctl -b | grep -i webkit

Log Analysis

This step regularly surfaces hidden segmentation faults, pointer errors, or system library linkage omissions not printed to the application's standard terminal output.

Step 9 — Isolate Local User Profile Corruption⚓︎

Isolate Local User Profile Corruption

Determine if the root cause resides within user configuration directories (~/.config, ~/.local) or is a persistent system-wide fault.

sudo useradd -m testwebkit

sudo passwd testwebkit

Test Protocol

  1. Log out of your desktop environment.
  2. Log in as the newly created testwebkit user profile.
  3. Execute devhelp from a terminal window.
Result Profile Root Cause Domain
Interface Renders Successfully Dotfile/Cache corruption within your primary home directory.
Interface Remains Blank System-wide package, library, or hardware driver failure.

Step 10 — Nuclear User Cache Reset⚓︎

Nuclear User Cache Reset

If Step 9 proved the issue is isolated to your primary user profile, execute a complete clearance of local transient caches.

rm -rf ~/.cache/*

Precautionary Step

Ensure all work is saved. Log completely out of your desktop session, then log back in to force all background user processes to re-initialize clean caches.

📝 Incident Data Collection Protocol⚓︎

Incident Data Collection Protocol

When anomalous rendering behaviors occur, immediately dump the system state metrics. Preserving this timeline context prevents trial-and-error debugging later.

Capture operational snapshot

date > issue.log

uname -a >> issue.log

pacman -Q webkit2gtk-4.1 javascriptcoregtk-4.1 mesa >> issue.log

Extract the recent delta of the system log

journalctl -b --since "10 minutes ago" >> issue.log

Lessons Learned Notebook

Always record the exact packages updated in the transaction preceding a WebKit crash event. Correlating package rollouts to application behavior reduces diagnostic mazes into predictable, 2-minute resolutions.

👉 Advanced-Configuration

REMARKABLE SCROLL FIX — SUMMARY⚓︎

What we did

  • Confirmed you use jamiemcg/Remarkable (GTK, v1.95-3 from AUR), not the JS library
  • Backed up the original file: ~/RemarkableWindow.py.orig
  • Took the scrolling fix (only) from GitHub issue #434 — preview now follows your cursor to the line you're editing instead of jumping to the top
  • Built it into a script: ~/Downloads/remarkablescroll/make_scroll_only.py
  • Tested it in a throwaway copy (~/remarkable-test) before touching anything real
  • Installed it into the real app, so your normal icon/double-click already uses it

What's on your system now:

  • ~/RemarkableWindow.py.orig — untouched original, keep this!
  • ~/RemarkableWindow.py.scroll — the patched version, currently installed
  • ~/Downloads/remarkablescroll/make_scroll_only.py — the script that builds it
  • ~/remarkable-test/ — the test copy, safe to delete anytime

If an update ever overwrites the fix.

If a Remarkable package update ever overwrites the fix, reapply it with:

python3 ~/Downloads/remarkablescroll/make_scroll_only.py ~/RemarkableWindow.py.orig ~/RemarkableWindow.py.scroll

sudo cp ~/RemarkableWindow.py.scroll /usr/share/remarkable/remarkable/RemarkableWindow.py

NOTE

This only works cleanly if the update is still version 1.95. If it's a newer version, the surrounding code may have changed and the script's edits might not match — bring it back to me and I'll check.

Not fixed: the whole preview still re-renders on every change, so very long chapters may still feel a bit heavy, just no longer disorienting.