Apex DateTime.format with Unrecognized Timezone Identifier – Missing Validation Constraint

Apex DateTime.format and Unrecognized Timezones

When you call DateTime.format(String, String) with a second argument that is not a valid IANA time‑zone ID, the platform does not throw an exception. Instead, it silently substitutes the organization’s default time zone and returns the formatted string based on that fallback.

Why the Silent Fallback Exists

• The Salesforce documentation lists this behavior as the default: an unrecognized ID is treated as if the org’s time zone had been requested.
• No exception or error message is emitted, so code that relies on the exact zone can silently produce wrong results, especially around daylight‑saving changes.
• There is currently no org‑level or deployment‑time setting that can change this behavior to a stricter validation mode.

What Developers Should Do

1. Validate the ID yourself before calling format. A common pattern is to keep a static Set of known IANA zones and check membership:

public class TimeZoneHelper {
    private static final Set VALID_ZONES = new Set{
        'America/New_York', 'Europe/London', 'Asia/Tokyo' // … add all needed zones
    };

    public static void validate(String zoneId) {
        if (!VALID_ZONES.contains(zoneId)) {
            throw new IllegalArgumentException('Invalid time zone: ' + zoneId);
        }
    }
}

// Usage
TimeZoneHelper.validate(myZoneId);
String formatted = myDateTime.format('yyyy-MM-dd HH:mm:ss', myZoneId);

2. Alternatively, use TimeZone.getTimeZone(String) (if available in your org) to attempt to resolve the ID; a null return indicates an invalid zone.
3. For integrations that must support a dynamic list of zones, consider pulling the IANA list from an external service (e.g., the IANA Time Zone Database) at deployment time and caching it in a custom setting or custom metadata type.
4. Log or alert when a fallback occurs. A simple System.debug or custom logging component can surface unexpected substitutions early.

No Platform Configuration Exists

At this time, Salesforce provides no configuration option—neither org‑wide nor deployment‑specific—to enforce strict validation of the timezoneId argument. The fallback behavior is baked into the runtime.

Practical Verification Steps

• Write a test method that calls DateTime.now().format('yyyy-MM-dd HH:mm:ss', 'Invalid/Zone') and assert that the output’s offset matches the org’s default offset.
• Repeat the test with a known valid zone, such as 'America/New_York', and verify the offset difference.
• Check the debug logs for any exception entries; none should appear for the invalid ID case.

Ask for Missing Diagnostic Detail

To fine‑tune your validation strategy, it can help to know the org’s default time zone. If it’s not already documented in your integration spec, you might want to add that detail.