Runtime error converting local time to UTC with Gleam's DateTime module

Conversion Behavior and Failure Modes

In Gleam, timezone handling is delegated to the Erlang/OTP runtime. Because the standard library does not maintain its own timezone database, the behavior of local-to-UTC conversions depends entirely on the underlying BEAM VM version.

1. Missing Timezone Identifiers

When a timezone identifier (e.g., "Invalid/Zone") is not present in the VM's database, the conversion does not return a Result or silently fall back to UTC. Instead, it raises a runtime error (typically a badarg in Erlang), which will crash the current Gleam process. There is no built-in compile-time validation for IANA strings.

2. DST Fall-back Ambiguity

During a daylight-saving "fall-back" transition, a local wall-clock time occurs twice. The Erlang calendar functions used by Gleam's ecosystem typically return a list of possible universal times for that local time. If the conversion wrapper you are using only returns a single value, it is applying a specific resolution strategy (such as picking the first occurrence). However, the VM itself provides both candidates, meaning the resolution is a logic decision made by the library or your code, not a fixed VM default.

3. Validating Supported Zones

There is no documented function to enumerate all supported IANA identifiers. The most reliable way to validate a zone is to attempt a conversion of a known fixed date at application startup. If the identifier is invalid, the process will crash immediately, allowing you to catch configuration errors during deployment rather than at runtime.

Practical Verification

To verify how your specific OTP version handles these cases, you can use the Erlang shell (erl) to test the underlying logic:

% Test for crash on invalid zone
calendar:local_time_to_universal_time_dst({2026, 10, 13, 12, 0, 0}, "Invalid/Zone").

% Test for ambiguity during DST fall-back (Europe/Berlin)
calendar:local_time_to_universal_time_dst({2026, 10, 25, 2, 30, 0}, "Europe/Berlin").

Assumptions and Constraints

• OTP Version: This behavior assumes OTP 26+. Earlier versions may have different calendar module semantics.
• Library Wrappers: This assumes you are using standard FFI wrappers around Erlang's calendar. If you are using a third-party Gleam library that implements its own parsing logic, check that library's source for Result-based error handling.

Diagnostic Request: To provide a more specific code fix, please specify which Gleam library (or custom FFI) you are using to call the Erlang calendar functions, as this determines if the crash is wrapped in a Result or left as a runtime exception.