[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