The DuckDB Local UI ships as the ui extension, first available in DuckDB 1.2.1. When it does not work, the cause is almost always one of: DuckDB is older than 1.2.1, the ui extension cannot fetch its assets from https://ui.duckdb.org, port 4213 is blocked, or you are running DuckDB on a remote host with no way for a local browser to reach it.
- ·DuckDB is older than 1.2.1, so start_ui and the -ui flag do not exist
- ·The extension cannot reach https://ui.duckdb.org because of a proxy, firewall, or SSL policy
- ·Port 4213 is already in use, or blocked by a local firewall
- ·You are running DuckDB over SSH, in Docker, or on a cloud VM with no port forwarding
- ·You are on windows_arm64, which the ui extension does not currently ship for
What you're seeing
The failure mode depends on what is actually broken. Older DuckDB builds do not know the -ui flag or the start_ui function at all. Newer ones start the local HTTP server but cannot reach the remote asset host, or open a browser tab that never loads.
# Old DuckDB, no ui extension:
$ duckdb -ui
unknown command line argument: ui
# Extension not autoloaded, or autoload disabled:
D CALL start_ui();
Catalog Error: Table Function with name start_ui does not exist!
Did you mean "pragma_version"?
# Extension loaded but cannot fetch UI assets:
D CALL start_ui();
IO Error: Could not fetch: '/' from 'https://ui.duckdb.org':
Could not establish connection
# Corporate SSL inspection:
IO Error: Could not fetch: '/' from 'https://ui.duckdb.org':
SSL server verification failed
# Port already in use:
IO Error: Failed to bind to 127.0.0.1:4213: Address already in useduckdb ui not working, duckdb ui not loading, duckdb ui not starting, duckdb -ui not working, duckdb start_ui does not exist, duckdb ui could not fetchWhat's causing this
Ranked most-likely first.
- 1
DuckDB is older than 1.2.1
The ui extension first shipped with DuckDB 1.2.1 in March 2025. Any older build does not recognise the -ui flag on the CLI or the start_ui() table function, and no amount of INSTALL / LOAD will help because the extension is not published for those versions.
- 2
The ui extension is not installed or not autoloaded
start_ui lives inside the ui extension. If autoloading is disabled (SET autoload_known_extensions=false), or the first install failed silently, calling start_ui() surfaces a Catalog Error even on a version that supports the UI.
- 3
The local HTTP server cannot reach https://ui.duckdb.org
The extension starts a local server on 127.0.0.1:4213, but that server fetches the actual UI assets from ui.duckdb.org so they can update independently of DuckDB itself. A corporate proxy, air-gapped network, or a firewall that blocks outbound HTTPS on the DuckDB process breaks that fetch and the browser tab sits blank.
- 4
Corporate SSL inspection is rewriting the certificate
Many enterprise networks terminate HTTPS with an internal certificate authority. DuckDB does not trust that CA by default, so the fetch fails with SSL server verification failed even though the target is reachable.
- 5
Port 4213 is already bound
The default UI port is 4213. If another DuckDB session, a stray previous run, or an unrelated process already holds it, start_ui either fails to bind or returns a URL that lands on the wrong process.
- 6
DuckDB is on a remote host and the browser is not
duckdb -ui only opens a browser on the machine running DuckDB. On an SSH session, a container, a WSL shell, or a cloud VM, the UI server binds to that machine's localhost and your laptop cannot reach it without port forwarding or a published Docker port.
- 7
windows_arm64 has no ui extension
DuckDB does not currently publish the ui extension for windows_arm64. On Snapdragon and other ARM Windows devices, INSTALL ui fails with a download error and there is no supported workaround short of running the x64 build under emulation or switching to WSL.
How to fix it
Step 1: confirm DuckDB is 1.2.1 or newer
Nothing else matters if the binary predates the UI. Check the version, and if it is too old, install a current release. Homebrew, the standalone CLI, and the Python client all ship the ui extension as of 1.2.1.
SELECT version();
-- v1.2.1 or higher is required. If below, upgrade before continuing.Step 2: install and load the ui extension explicitly
If start_ui returns a Catalog Error, the extension is not loaded in this session. Install and load it by hand, then retry. This also confirms that the extension can actually be downloaded from your network.
INSTALL ui;
LOAD ui;
CALL start_ui();
-- If autoload was the real problem, re-enable it for future sessions:
SET autoinstall_known_extensions = 1;
SET autoload_known_extensions = 1;Step 3: check that port 4213 is free
The local server binds to 127.0.0.1:4213. If it is already in use, either stop the process holding it or point the UI at a different port with ui_local_port before calling start_ui.
# macOS / Linux:
lsof -iTCP:4213 -sTCP:LISTEN
# Windows PowerShell:
Get-NetTCPConnection -LocalPort 4213Step 4: change the UI port if 4213 is taken or firewalled
ui_local_port sets a different bind port for the local HTTP server. Useful when 4213 is in use, or when a local firewall rule only allows a specific port range. Then open the shown URL manually if the browser did not launch.
SET ui_local_port = 4300;
CALL start_ui_server();
-- Then open http://localhost:4300 in a browser.Step 5: forward the UI port from a remote host
When DuckDB runs on a remote server over SSH, ask ssh to tunnel 4213 back to your laptop. The -T flag keeps the session non-interactive and the trailing command starts DuckDB with the UI on the remote side.
# From your laptop, tunnel and start the UI in one command:
ssh -L 4213:localhost:4213 -T user@remote-host /usr/local/bin/duckdb -ui
# Then open http://localhost:4213 in your local browser.Step 6: publish the UI port from Docker
Inside a container, start_ui() binds to the container's localhost, which is unreachable from the host. Publish 4213 when you run the container, then start the server without a browser and open it from the host.
docker run -it --rm -p 4213:4213 \
-v $(pwd):/data \
duckdb/duckdb -c "CALL start_ui_server();" \
--interactive
# Then open http://localhost:4213 on the host machine.Step 7: get through a corporate proxy or SSL policy
If the fetch to ui.duckdb.org fails, tell DuckDB about your proxy. If SSL inspection rewrites the certificate and you cannot install the internal CA into the DuckDB trust store, disable verification for the UI fetch specifically. Only do that on networks you actually trust.
-- Route DuckDB's HTTP client through the corporate proxy:
SET http_proxy = 'proxy.mycompany.com:3128';
-- Last-resort workaround for SSL inspection on a trusted network:
SET ui_disable_server_certificate_verification = 1;
CALL start_ui();Step 8: work around windows_arm64
The ui extension is not published for windows_arm64. On ARM Windows, either run the x64 DuckDB binary under Prism emulation, or install DuckDB inside WSL and run the UI there. The Linux ARM build does include the ui extension.
# Inside WSL (Ubuntu):
curl https://install.duckdb.org | sh
~/.duckdb/cli/latest/duckdb -ui
# Then open http://localhost:4213 in a Windows browser
# (WSL forwards localhost automatically).Step 9: stop and restart the server cleanly
If the UI is stuck, a blank tab is loaded, or you changed a setting mid-session, shut the server down before restarting. Stopping and starting is cheap and avoids leftover state.
CALL stop_ui_server();
CALL start_ui();Prevention
Pin a minimum DuckDB version in project setup docs, README, or containers. 1.2.1 is the floor for the local UI, and there is no benefit to leaving old installs around when new users will hit the missing-flag error immediately.
On corporate machines, put SET http_proxy and, if unavoidable, SET ui_disable_server_certificate_verification into a startup script so every session inherits the working configuration. Nothing is more annoying than remembering four SET statements every time you open the shell.
For anyone regularly running DuckDB on remote hosts or in containers, wrap the SSH tunnel or docker run command in a shell alias. It is the difference between a one-line command and a rediscovery every time.
Debug DuckDB faster
1bench is a native GUI for DuckDB. Inspect queries, connections, and settings without leaving the app. See what's happening before you have to Google it.
Open DuckDB in 1bench