fix/duckdb/failed-to-download-extension
DuckDB error

Failed to download extension

Updated Aug 27, 20265-min read
TL;DR

DuckDB tried to fetch an extension binary from extensions.duckdb.org and the HTTP request failed. Usually a network path issue (firewall, proxy, offline machine) or a wrong repository/version combination for the extension you asked for.

  • ·The machine cannot reach extensions.duckdb.org (firewall, air-gapped, corporate network)
  • ·You are behind an HTTP proxy that DuckDB is not configured to use
  • ·The extension only exists in the community repository and you did not say FROM community
  • ·You are on a nightly or development build whose version has no matching extension binary
  • ·The extension does not exist for your platform yet (freshly released version, uncommon arch)
CHECK FIRSTCopy the URL from the error message and open it in a browser or curl it. If the download works there but not in DuckDB, it is a proxy or client problem, not a missing extension.

What you're seeing

DuckDB prints the extension name and the full URL it tried to fetch, followed by the HTTP status code. The URL tells you which version, platform, and repository were used, which is often the whole diagnosis.

text
-- HTTP 403 (blocked, often by firewall or country restriction):
HTTP Error: Failed to download extension "httpfs" at URL
"http://extensions.duckdb.org/v1.4.0/osx_arm64/httpfs.duckdb_extension.gz" (HTTP 403)

-- HTTP 404 (extension does not exist at that path):
IO Error: Failed to download extension "spatial" at URL
"http://extensions.duckdb.org/v1.4.0/linux_amd64_gcc4/spatial.duckdb_extension.gz" (HTTP 404)

-- Network unreachable (no HTTP response at all):
IO Error: Failed to download extension "httpfs". Connection error for HTTP HEAD
to 'http://extensions.duckdb.org/v1.1.3/windows_amd64/httpfs.duckdb_extension.gz'
Also seen as: duckdb failed to download extension, duckdb http error failed to download extension, duckdb io error failed to download extension, duckdb extension not available, duckdb install httpfs failed, duckdb install extension not working

What's causing this

Ranked most-likely first.

  1. 1

    Machine has no network path to extensions.duckdb.org

    The download hits a corporate firewall, an air-gapped host, or a container with restricted egress. HTTP 403 and outright connection failures usually land here. The URL in the error message resolves fine from your laptop but not from where DuckDB is running.

  2. 2

    Behind an HTTP proxy that DuckDB is not using

    DuckDB does not read http_proxy or https_proxy environment variables when downloading extensions. The proxy has to be set inside DuckDB with SET http_proxy or via a Secrets Manager http_proxy secret. Without that, every extension install goes direct and gets blocked.

  3. 3

    Extension lives in the community repository, not core

    INSTALL name defaults to the core repository. Community extensions (like prql, h3, shellfs, and many others) live at community-extensions.duckdb.org and return HTTP 404 from the default core URL. You need INSTALL name FROM community.

  4. 4

    Running a nightly or self-built DuckDB

    Extension binaries are built and published per release version. If PRAGMA version returns a hash rather than something like v1.4.0, the extension server has nothing at that path. Nightly builds need FROM core_nightly, and self-built binaries usually need extensions built from source too.

  5. 5

    Extension not yet published for your version or platform

    Right after a DuckDB release the extension server is populated over a few hours, and some platforms (uncommon Linux arch, older glibc builds) can lag or be missing entirely. The URL is correct, the file is not there yet.

  6. 6

    HTTP 451 country restriction

    The extension CDN returns HTTP 451 in a handful of jurisdictions. In that case no amount of retrying against extensions.duckdb.org will work and you need to point DuckDB at a mirror or install the extension file manually.

How to fix it

Step 1: confirm the URL is actually reachable from this machine

Copy the URL out of the error message and hit it with curl on the same host DuckDB is running on. If curl also fails, it is a network problem, not a DuckDB problem, and no SET command will fix it.

bash
curl -I "http://extensions.duckdb.org/v1.4.0/osx_arm64/httpfs.duckdb_extension.gz"

# Expect: HTTP/1.1 200 OK
# If you get 403, 451, or connection refused, the fix is at the network layer.

Step 2: if the extension is a community extension, say so

The default INSTALL uses the core repository. Community extensions need the repository specified explicitly. This alone fixes most HTTP 404 errors on extensions that clearly exist.

sql
-- Instead of:
INSTALL prql;

-- Use:
INSTALL prql FROM community;
LOAD prql;

-- For nightly builds:
INSTALL httpfs FROM core_nightly;

Step 3: configure the proxy inside DuckDB

Environment variables are ignored for extension downloads. Set http_proxy inside the session before INSTALL, or create a persistent http_proxy secret if the proxy needs authentication.

sql
-- Simple proxy without auth:
SET http_proxy = 'proxy.company.com:3128';
INSTALL httpfs;
LOAD httpfs;

-- Authenticated proxy via Secrets Manager:
CREATE SECRET http_proxy (
    TYPE http,
    HTTP_PROXY 'http://proxy.company.com:3128',
    HTTP_PROXY_USERNAME 'user',
    HTTP_PROXY_PASSWORD 'pass'
);
INSTALL httpfs;

Step 4: download the extension file manually and install from disk

When the CDN is unreachable from the DuckDB host but reachable from somewhere, get the .duckdb_extension.gz file off a machine that can reach it and install it by local path. Works for air-gapped hosts and HTTP 451 cases.

sql
-- 1. On any machine with network access, grab the exact URL from the error:
--    curl -O http://extensions.duckdb.org/v1.4.0/osx_arm64/httpfs.duckdb_extension.gz
--    gunzip httpfs.duckdb_extension.gz
--
-- 2. Move the .duckdb_extension file to the target host, then:
INSTALL '/path/to/httpfs.duckdb_extension';
LOAD httpfs;

-- If a version mismatch complains, force it:
FORCE INSTALL '/path/to/httpfs.duckdb_extension';

Step 5: point DuckDB at a mirror using custom_extension_repository

If you host an internal mirror of the extensions server (common in regulated environments), redirect the download to it. This scopes to the whole session and applies to every subsequent INSTALL.

sql
SET custom_extension_repository = 'http://extensions.mirror.internal';
INSTALL httpfs;
LOAD httpfs;

Step 6: if you are on a dev build, use a release build instead

Extensions are only published for tagged releases and nightly builds. A locally compiled DuckDB or a dev snapshot version will get HTTP 404 for every extension. Switch to an official release binary or build the extensions you need from source alongside DuckDB.

sql
-- Check what version DuckDB is reporting:
PRAGMA version;
-- If this returns a git hash rather than 'v1.x.y', you are on a dev build.
-- Install the official release from https://duckdb.org/docs/installation/ .

Prevention

In production, bake the extensions you need into the image or the volume rather than downloading them on every cold start. INSTALL writes to the extension directory once, LOAD is cheap thereafter, and every container that ships without pre-installed extensions is one CDN outage away from a broken cold path.

If the environment sits behind a corporate proxy, put SET http_proxy in the connection init script so every session inherits it. The same script is the right place for SET custom_extension_repository when the org runs a mirror.

For repeatable builds pin the DuckDB version and cache the .duckdb_extension files alongside your build artifacts. That way a re-run does not depend on extensions.duckdb.org being up, and you do not get surprised when a new release temporarily lacks a binary for your platform.

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