Skip to content

Document config-shaping env vars delivered via loadEnv .env files #564

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
kylebernhardy wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Document config-shaping env vars delivered via loadEnv .env files #564

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
067593e
Document config-shaping env vars via loadEnv (harper#1580)
nizzlenitz Jul 2, 2026
938746d
Clarify override belongs to the loadEnv config block
nizzlenitz Jul 2, 2026
43f7c75
Pivot to warn-don't-honor per harper#1580 direction
nizzlenitz Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions reference/environment-variables/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,16 @@ loadEnv:

Files are loaded in the order specified.

## Config-Shaping Variables Are Not Honored

<VersionBadge type="changed" version="v5.2.0" />

The three configuration env vars — `HARPER_DEFAULT_CONFIG`, `HARPER_CONFIG`, and `HARPER_SET_CONFIG` (see [Configuration](../configuration/overview.md)) — shape Harper's root configuration, which is composed once at startup, **before components load**. Delivering one of them through a `loadEnv` `.env` file therefore has **no effect**: configuration is strictly top-down (the instance's configuration controls components, never the reverse), so a component cannot shape instance-wide config.

As of 5.2.0 this is no longer silent: Harper logs a prominent warning at startup for each config-shaping variable found in a component `.env` file — naming the variable and the file — and again at component load time (which also covers components deployed after startup). Earlier versions ignored these variables without any message.

To configure the instance, use the supported channels instead: set the variable in the process environment (container env, service unit, shell), or put the equivalent keys in the instance's `harper-config.yaml`.

## Related

- [Components Overview](../components/overview.md)
Expand Down