In Jenkins headless execution, the application navigates to the correct URL but fails to render the UI, resulting in a blank page with no visible elements

Web Testing
, , ,
1

Jenkins (Linux) runs Chrome in headless mode
Navigation succeeds → URL is correct
But UI never renders, so my script keeps failing with the element not found error as the username/password fields don’t exist in the UI and it displays just blank screen in the screenshot @Elly_Tran

image
image1920×1080 60.7 KB

2

Problem Analysis

Your issue is a classic headless Chrome rendering problem on Linux. The navigation succeeds (URL loads correctly), but the UI doesn’t render, resulting in a blank screen and “element not found” errors. This occurs because headless Chrome on Linux requires proper graphics rendering support—without a virtual display server or proper configuration, Chrome renders the page but doesn’t display UI elements correctly.

Root Causes:

  1. Missing virtual display server – Linux headless environments lack a display server (X11)
  2. Viewport size issues – Headless Chrome defaults to 800x600, which may be too small for your application
  3. Timing differences – Elements may not be fully rendered when headless mode loads faster
  4. Chrome version-specific bugs – Chrome 129+ has known rendering issues in headless mode

Solutions

Solution 1: Install and Configure Xvfb (Virtual Display Server) :star: RECOMMENDED FOR JENKINS

This is the official Katalon-recommended approach for Jenkins on Linux.

Steps:

  1. Install Xvfb on your Linux machine:

    sudo apt install -y xvfb

  2. Configure Jenkins to use Xvfb (if using Katalon plugin for Jenkins):

    • In your Jenkins job configuration, set the Xvfb-run configuration to:

      -a -n 0 -s "-screen 0 1024x768x24"

    • This creates a virtual display at 1024x768 resolution with 24-bit color depth

  3. For manual execution, run your tests with:

    Xvfb :0 >& /dev/null &
export DISPLAY=:0
# Then run your Katalon tests

Why this works: Xvfb creates a virtual X11 display server in memory, allowing Chrome to render graphics without a physical monitor. This is the standard solution for headless Linux servers.

Solution 2: Configure Headless Chrome Desired Capabilities

Adjust Chrome’s rendering behavior in Katalon Studio:

  1. Go to Project > Settings > Desired Capabilities > WebUI > Chrome (headless)
  2. Add these capabilities:
Name Type Value
args List --window-size=1024,768
args List --disable-gpu
args List --no-sandbox

Step-by-step in Katalon:

  • Click Add for each capability
  • For args, select List type and add each flag separately

Why these flags help:

  • --window-size=1024,768 – Sets a larger viewport (default is 800x600)
  • --disable-gpu – Disables GPU acceleration (often causes rendering issues on Linux)
  • --no-sandbox – Bypasses sandbox restrictions (common in CI/CD environments)

Solution 3: Fix Chrome 129+ Blank Window Issue

If you’re using Chrome version 129 or later and seeing a blank white window:

  1. Go to Project > Settings > Desired Capabilities > WebUI > Chrome (headless)

  2. Add this parameter:

    --window-position=-10000,-10000

This hides the blank window that appears due to a known Chrome 129 bug.

Solution 4: Increase Wait Times and Add Explicit Waits

Headless mode loads faster, which can cause timing issues:

// In your test script
WebUI.waitForPageLoad(10)  // Wait for page to fully load
WebUI.waitForElementPresent(findTestObject('Object Repository/username_field'), 10)
WebUI.setText(findTestObject('Object Repository/username_field'), 'username')

Solution 5: Complete Jenkins Configuration Example

For Jenkins on Ubuntu with Katalon plugin:

Build Step Configuration:

  • Katalon Studio version: (e.g., 9.3.0)

  • Command arguments:

    -browserType="Chrome" -retry=0 -statusDelay=15 -testSuitePathTest Suites/TS_RegressionTest

  • X11 DISPLAY (for Linux): Leave blank (Xvfb handles this)

  • Xvfb-run configuration (for Linux):

    -a -n 0 -s "-screen 0 1024x768x24"

Key Considerations

Issue Solution
Blank screenshots in Jenkins Install Xvfb and configure Xvfb-run in Jenkins job
Elements not found in headless Add --window-size=1024,768 and --disable-gpu to desired capabilities
Chrome 129 blank window Add --window-position=-10000,-10000 to desired capabilities
Permission denied errors Run sudo chmod -R 777 <katalon-project-path>
“Unable to init server” error Ensure Ubuntu uses OpenJDK 8 (java -version)
Timing issues Add explicit waits with WebUI.waitForElementPresent()

References

3

hi @v.deenadayalan

this is almost certainly a missing display server or viewport issue on your headless Linux Jenkins agent. Two things to fix:

first, install and use Xvfb so Chrome has a virtual display to render against. On your Jenkins agent run sudo apt install -y xvfb, then in your Jenkins job set the Xvfb-run configuration to -a -n 0 -s "-screen 0 1920x1080x24". If you are using the Katalon Jenkins plugin, there is a dedicated Xvfb field in the build step configuration.

second, set proper Chrome headless desired capabilities in Project Settings under Desired Capabilities > WebUI > Chrome (headless). Add --window-size=1920,1080, --disable-gpu, and --no-sandbox as list-type args. If you are on Chrome 129+, also add --headless=new which uses the newer headless mode that renders more faithfully than the old default.

4

Headless Chrome Linux/Jenkins blank UI = missing virtual display + viewport.

Fix 1: Xvfb (Linux/Jenkins)

sudo apt install xvfb
Jenkins Job > Katalon Plugin > Xvfb-run: -a -n 0 -s "-screen 0 1024x768x24"

Fix 2: Desired Capabilities (Katalon)

Project > Settings > Desired Capabilities > Chrome (headless):

Name Type Value

Name Type Value
args List –no-sandbox
args List –disable-gpu
args List –window-size=1920,1080
args List –disable-dev-shm-usage
args List –window-position=-10000,-10000 // Chrome 129+

Script Waits

WebUI.openBrowser('')  // Headless auto
WebUI.maximizeWindow()
WebUI.waitForPageLoad(30)
WebUI.waitForElementPresent(username, 20)

Run: DISPLAY=:99 ./katalon or Docker Xvfb.

5

@v.deenadayalan This is not a Katalon issue but an environment + browser rendering problem in headless Linux. Fixing display context (Xvfb) and Chrome flags resolves this issue. which most of the other users have already posted, try them, you issue will get resolved.