Skip to content

Document that DuckDB extension installs need a HOME directory - #74301

Merged
ferruzzi merged 2 commits into
apache:mainfrom
aws-mwaa:duckdb-home-directory-docs
Oct 6, 2026
Merged

ferruzzi merged 2 commits into
apache:mainfrom
aws-mwaa:duckdb-home-directory-docs

Conversation

@ferruzzi

@ferruzzi ferruzzi commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

DuckDB installs extensions under the user's home directory and fails with "IO Error: Can't find the home directory" when HOME is unset or empty, which is the default state of an AWS Lambda function. Providing a writable home directory is part of configuring the environment rather than something the provider can guess, since any directory it picked would be discarded when the task exits and so would re-download every extension.

Document the requirement in the DuckDB connection docs, in the Amazon DuckDB operator docs where the two S3 extensions are installed by default, and in the Lambda executor docs. Set HOME in the Lambda reference Dockerfile beside the existing AIRFLOW_HOME, which is the same /tmp constraint.

Checked against duckdb 1.2.0, 1.3.0, 1.3.2, 1.4.0, 1.4.1, 1.5.0 and 1.5.5: an install fails on every version without a usable HOME, extension_directory stops covering for a missing HOME at 1.5.0, and loading a pre-populated extension_directory with autoinstall_extensions disabled works everywhere.

Follow-up instead of #74126


Was generative AI tooling used to co-author this PR?
  • [ x ] Yes (please specify the tool below)
    Version confirmations done by Claude Opus 5

  • Read the Pull Request Guidelines for more information. Note: commit author/co-author name and email in commits become permanently public when merged.
  • For fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
  • When adding dependency, check compliance with the ASF 3rd Party License Policy.
  • For significant user-facing changes create newsfragment: {pr_number}.significant.rst, in airflow-core/newsfragments. You can add this file in a follow-up commit after the PR is created so you know the PR number.

DuckDB installs extensions under the user's home directory and fails with
"IO Error: Can't find the home directory" when HOME is unset or empty,
which is the default state of an AWS Lambda function. Providing a writable
home directory is part of configuring the environment rather than something
the provider can guess, since any directory it picked would be discarded
when the task exits and so would re-download every extension.

Document the requirement in the DuckDB connection docs, in the Amazon
DuckDB operator docs where the two S3 extensions are installed by default,
and in the Lambda executor docs. Set HOME in the Lambda reference
Dockerfile beside the existing AIRFLOW_HOME, which is the same /tmp
constraint.

Checked against duckdb 1.2.0, 1.3.0, 1.3.2, 1.4.0, 1.4.1, 1.5.0 and 1.5.5:
an install fails on every version without a usable HOME, extension_directory
stops covering for a missing HOME at 1.5.0, and loading a pre-populated
extension_directory with autoinstall_extensions disabled works everywhere.
Comment thread providers/amazon/docs/executors/lambda-executor.rst Outdated
Comment thread providers/duckdb/docs/connections/duckdb.rst Outdated
Comment thread providers/duckdb/docs/connections/duckdb.rst Outdated
Comment thread providers/duckdb/docs/connections/duckdb.rst Outdated
@ferruzzi
ferruzzi merged commit 95b5d83 into apache:main Oct 6, 2026
89 checks passed
@ferruzzi
ferruzzi deleted the duckdb-home-directory-docs branch October 6, 2026 18:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:production-image Production image improvements and fixes area:providers kind:documentation provider:amazon AWS/Amazon - related issues provider:duckdb

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants