[AP24110011695]

Issue number: closes #8747

Summary

Changes

resolve_max_age() is a raw int(env), so an empty or non-integer POWERTOOLS_PARAMETERS_MAX_AGE raised ValueError from every Parameters/Secrets/AppConfig entry point (12 call sites) before any AWS call was made.

• Added resolve_parameters_max_age() in utilities/parameters/base.py: an explicit choice always wins; otherwise the environment variable is parsed, and a ValueError emits a PowertoolsUserWarning naming the ignored value and falls back to the documented default (DEFAULT_MAX_AGE_SECS = 300s), per ADR 0006 (warn now, harden in a future major).
• All 12 call sites (base ×2, ssm ×6, secrets ×3, appconfig ×1) now use the helper; dead imports (resolve_max_age, and os/constants/DEFAULT_MAX_AGE_SECS where no longer used) removed.
• Behavior shape matches fix(idempotency): treat empty or unparsable POWERTOOLS_IDEMPOTENCY_DISABLED as not disabled #8734 on the Idempotency side (malformed value → safe default, no crash); the notice is a PowertoolsUserWarning per ADR 0006 rather than a debug log — happy to align with fix(idempotency): treat empty or unparsable POWERTOOLS_IDEMPOTENCY_DISABLED as not disabled #8734's debug-log style if you prefer the two byte-identical.
• Recognized integer values — including 0 (no caching) — behave exactly as before.

User experience

Before: POWERTOOLS_PARAMETERS_MAX_AGE="" (a common config-drift case) made get_parameter(), get_secret(), SSMProvider().get() and every other lookup raise ValueError: invalid literal for int() with base 10: '' until the environment was fixed.

After: the same calls succeed with the documented default caching age, and one warning names the ignored value so the typo is visible.

Verification

• Failing-first regression test test_ssm_provider_get_with_invalid_max_age_env_var (tests/functional/parameters/_boto3/test_utilities_parameters.py): on develop (bc3136c) it fails with the reported ValueError; with this change it passes for both "" and "abc", asserting the warning, the returned value, and that the SDK call still happens.
• uv run pytest tests/functional/parameters tests/unit/test_shared_functions.py: 263 passed.
• Downstream consumer: uv run pytest tests/functional/feature_flags: 191 passed.
• Full uv run pytest tests/unit: 626 passed; the 8 failures are pre-existing on clean develop on this machine (missing optional extras aws_xray_sdk etc.) and unrelated to this change.
• uv run mypy aws_lambda_powertools/utilities/parameters/: clean; ruff format + ruff check clean on all touched files.
• Repro also run end-to-end outside pytest on develop before filing Bug: POWERTOOLS_PARAMETERS_MAX_AGE set to an empty or non-integer value crashes every parameters call #8747 (empty and non-integer crash; unset baseline reaches the SDK).

This PR was prepared with AI assistance; the repro, tests and every run above were executed and verified by me against develop (bc3136c) as described.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Manishram-ai]

Thanks for this. I called nine public entry points (get_parameter, get_parameters, get_parameters_by_name, SSMProvider.get, SSMProvider.get_parameters_by_name, get_secret, get_secrets_by_name, SecretsProvider.get and get_app_config) with the providers' fetch methods stubbed, and POWERTOOLS_PARAMETERS_MAX_AGE set to "" and then "abc". On develop all nine raise ValueError: invalid literal for int() with base 10: ''. On this branch they all return, each one emits a single PowertoolsUserWarning, and the warning points at my calling line every time, so stacklevel=3 works for both the module functions and the provider methods. tests/functional/parameters, tests/unit/test_shared_functions.py and tests/functional/feature_flags pass (454 tests), and the new test fails on develop with the original ValueError.

Separate from this PR, the same config-drift case exists for POWERTOOLS_PARAMETERS_SSM_DECRYPT. With it set to "", the five SSM entry points above raise ValueError: invalid truth value '' through resolve_truthy_env_var_choice, on develop and on this branch. Could be a good follow-up issue next to this one and #8728.

[Manishram-ai]

The docstring above says this hardens in a future major. If that's the plan, ADR 0006 asks for the warning itself to say what will change and when, so the message could mention that it becomes an error in the next major. If the fallback is meant to stay, the "harden in a future major" part of the docstring could go instead.