Repository navigation
Add debug logging for env_file and secret file resolution - #913
Merged
Merged
Conversation
Extend the existing PYDANTIC_SETTINGS_DEBUG mechanism to trace file resolution, so users can see which dotenv and secret files were probed, which were loaded, and which were skipped. Previously a missing env_file (e.g. a relative .env path that doesn't resolve from the current working directory) was silently skipped with no indication why. The logger, debug env-var gate, and helper move to the dependency-free utils module so the dotenv and secrets sources can share them without a circular import. Co-Authored-By: Claude Opus 4.8 <[email protected]>
Contributor
There was a problem hiding this comment.
Pull request overview
Extends the existing PYDANTIC_SETTINGS_DEBUG diagnostics to include dotenv (env_file) and secrets directory file resolution, so users can see which files were probed, loaded, or skipped when debugging settings behavior.
Changes:
- Add
DEBUGlogs for dotenv file load/skip decisions inDotEnvSettingsSource._read_env_files. - Add
DEBUGlogs for per-field secret file load/skip decisions inSecretsSettingsSource.get_field_value. - Centralize the shared debug gate and logger in
pydantic_settings.utils, with corresponding docs + tests.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_settings.py | Adds regression tests asserting debug logs appear only when PYDANTIC_SETTINGS_DEBUG is enabled and logging is at DEBUG. |
| pydantic_settings/utils.py | Moves shared pydantic_settings logger + _settings_debug_enabled() helper into a dependency-light module for reuse. |
| pydantic_settings/sources/providers/secrets.py | Emits debug logs when secret files are found/loaded or missing/skipped. |
| pydantic_settings/sources/providers/dotenv.py | Emits debug logs when dotenv files are found/loaded or missing/skipped. |
| pydantic_settings/main.py | Switches to importing the shared logger/debug helper from utils to avoid duplication and keep existing references working. |
| docs/index.md | Documents the new file-resolution trace output under the existing debug flag section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Merged
3 of 13 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #909
Summary
Extends the existing
PYDANTIC_SETTINGS_DEBUGmechanism (added in #906) to also trace file resolution, so users can see which dotenv and secret files were probed, which were loaded, and which were skipped.Previously, a missing
env_file— e.g. a relative.envpath that doesn't resolve from the current working directory — was silently skipped with no indication why, which is the exact confusion reported in #909 (and echoed across #4, #266, #354, #215, #795). This reuses the existing opt-in gate andpydantic_settingslogger rather than introducing a parallel logging path.Changes
DotEnvSettingsSource._read_env_filesnow emitsDEBUGlines for each candidateenv_file—Loading env file: <resolved path>orEnv file not found, skipping: <resolved path>. Theif is_file()branch previously had noelse, so misses were invisible.SecretsSettingsSource.get_field_valuegets the same treatment for per-field secret files (which had an explicit# we currently don't return a warning for thiscomment).logger,_DEBUG_ENV_VAR, and_settings_debug_enabled()helper move into the dependency-freeutilsmodule so the sources can share them without a circular import.pydantic_settings.mainre-imports them, so existing references keep working.Behavior
Opt-in and off by default — output only appears when
PYDANTIC_SETTINGS_DEBUGis truthy andDEBUG-level logging is enabled on thepydantic_settingslogger. No change to default behavior.The resolved absolute paths can leak usernames/layout, so this sits behind the same opt-in gate covered by the existing sensitive-output warning in the docs.
Tests
Added
test_debug_env_file_resolution,test_debug_env_file_resolution_disabled_by_default, andtest_debug_secret_file_resolution. All debug tests pass;ruff check/formatclean.🤖 Generated with Claude Code