When running Selenium on a headless server (Linux without a GUI, or Docker container), GeckoDriver attempts to create a graphical display. If it fails, the entire service crashes with the localhost error.
Symptoms: The error occurs only in CI/CD (Jenkins, GitLab CI) but works on your local desktop.
The Fix – Use Virtual Display Framebuffer:
On Linux, install xvfb (X Virtual Framebuffer):
sudo apt-get install xvfb
xvfb-run python your_selenium_script.py
Or, use PyVirtualDisplay in Python:
from pyvirtualdisplay import Display
display = Display(visible=0, size=(1920, 1080))
display.start()
# Your Firefox driver code here
Selenium has no built-in "search" for GeckoDriver. If you don't tell it exactly where the executable is, it fails silently and throws this cryptic localhost error.
By default, GeckoDriver picks a random free port between 10000 and 60000. If that specific port is locked by another application (like Docker, a local web server, or another WebDriver instance), the bind fails.
The Fix: Enforce a specific, known-free port:
from selenium.webdriver.firefox.service import Service
service = Service(executable_path='path/to/geckodriver', port=7055) # Classic Selenium port driver = webdriver.Firefox(service=service)
Using port=7055 often resolves conflicts because it's a reserved port for WebDriver.
If you see an error like “cannot start the driver service on http://localhost:xxxxx” when using Selenium with Firefox in C#, this note explains common causes and fixes.