Bug: POWERTOOLS_PARAMETERS_MAX_AGE set to an empty or non-integer value crashes every parameters call #8747

Expected Behaviour

A malformed POWERTOOLS_PARAMETERS_MAX_AGE environment variable should not crash the Parameters utility. An empty or non-integer value is a configuration problem, so per the compatibility policy in ADR 0006 I would expect a PowertoolsUserWarning and a fallback to the documented default (DEFAULT_MAX_AGE_SECS, 5 seconds) — or at minimum a clear configuration error — so that a config typo degrades to the default caching behavior instead of breaking every parameter and secret lookup.

Current Behaviour

POWERTOOLS_PARAMETERS_MAX_AGE is resolved through resolve_max_age() (aws_lambda_powertools/shared/functions.py), which is a raw int(env). An empty string (common config drift: the variable defined but left empty in IaC/templates) or any non-integer value raises ValueError: invalid literal for int() with base 10: ... before any AWS call is made. The exception is raised before the cache lookup and before the provider's _get(), so every entry point is affected — 13 call sites: BaseProvider.get/get_multiple, all SSM providers and high-level functions (get_parameter, get_parameters, get_parameters_by_path, SSMProvider variants), Secrets (get_secret, get_secrets, SecretsProvider.get), and AppConfig (get_app_config, AppConfigProvider.get).

Observed with POWERTOOLS_PARAMETERS_MAX_AGE="" and "abc" (identical failure shape):

SSMProvider().get: ValueError: invalid literal for int() with base 10: ''
get_parameter:    ValueError: invalid literal for int() with base 10: ''
get_secret:       ValueError: invalid literal for int() with base 10: ''

Baseline with the variable unset behaves normally (the SDK call proceeds and fails only on the dummy credentials used in the repro).

This is the same failure class as #8728 (POWERTOOLS_IDEMPOTENCY_DISABLED crashing on non-boolean values, fixed by #8734 by treating unparsable values as the safe default).

Code snippet

import os

# Simulates config drift: variable defined but empty (same with "abc")
os.environ["POWERTOOLS_PARAMETERS_MAX_AGE"] = ""

from aws_lambda_powertools.utilities.parameters import get_parameter

value = get_parameter("/app/config")

Possible Solution

Mirror the #8734 approach in the Parameters utility: resolve POWERTOOLS_PARAMETERS_MAX_AGE through a small helper that treats empty/unparsable values as DEFAULT_MAX_AGE_SECS and emits a PowertoolsUserWarning naming the ignored value (per ADR 0006: warn now, harden later). Recognized integer values — including 0 (no caching) — behave exactly as today. The single helper in shared/functions.py's caller path (or wrapping resolve_max_age at the parameters boundary) covers all 13 call sites at once.

Steps to Reproduce

1. Set POWERTOOLS_PARAMETERS_MAX_AGE="" (or abc)
2. Call any Parameters/Secrets/AppConfig entry point, e.g. get_parameter("/app/config")
3. A raw ValueError: invalid literal for int() with base 10: '' is raised before any AWS call

I ran this against develop (bc3136c) with a stubbed-credentials environment; the exception surfaces identically from SSMProvider().get(), get_parameter() and get_secret(). With the variable unset, the same calls reach the SDK as expected.

Reproduction (was the snippet above executed?)

Yes, I ran it and saw the failure.

Powertools for AWS Lambda (Python) version

latest (develop bc3136c)

AWS Lambda function runtime

3.13

Packaging format used

PyPi

Debugging logs

Not applicable — the failure is independent of logging; no SDK call is reached.