Migration Experience from v0.0.17 → v1.1.0

Finally we were able to migrate to the latest version v1.1.0 but I am obliged to share our migration experience since this issue is about the lack of documentation. Hopefully this helps others and reinforces why proper migration docs are essential.

The Breaking Change We Found

After upgrading, our integration started returning 500 errors on generatewidgetsession. After investigating the SDK source code ourselves with the help of claude code, we discovered a silent breaking change with the providers parameter that now needs to be comma-separated, e.g., "GARMIN,GOOGLE" instead of a List[str] (e.g., ["GARMIN", "GOOGLE"]).

This isn't documented anywhere. The type hints in the new SDK show providers: Optional[str], but without a changelog or migration guide, there's no way to know this changed from accepting a list.

The Error Experience

When you pass the wrong type, the API returns:

status_code: 500
body: <!doctype html><title>500 Internal Server Error</title>...

No meaningful error message. No indication of what went wrong. Just a generic HTML error page.

The Support Experience

Since @12458 said that we could reach out via the support button on the dashboard and that they would be "happy to assist in migrating the app to the new SDK" I need to tell community about the support experience.

Following the suggestion in this thread, I opened a ticket describing the 500 error with generate_widget_session after upgrading to v1.1.0. The response asked for credentials and a "full reproducible snippet."

To be clear: I reported a 500 error occurring on Terra's servers, and the support response was to ask me to investigate further. The server logs showing the malformed request should have been enough to diagnose this internally. Instead, we had to:

Read through the SDK source code to understand the new method signatures
Compare with the old SDK to identify what changed
Write a reproduction script to prove the type mismatch
Report back with the root cause

This is the opposite of what "happy to assist you in migrating" suggests and it is not the first time support team just delegates the investigation to us.

Recommendations

Publish a changelog: The SDK is auto-generated by Fern. Diffing API definitions between versions to generate a
migration guide should be straightforward.
Validate input types: The SDK or API should reject invalid types with a clear error message, not a 500.
Improve support processes: When customers report 500 errors after upgrading, check your server logs before asking
them to debug it themselves.

Reproduction Script

For anyone else hitting this issue:

from terra import Terra

terra = Terra(dev_id="YOUR_DEV_ID", api_key="YOUR_API_KEY")

# This FAILS with 500 (v0.0.17 style)
terra.authentication.generatewidgetsession(providers=["GARMIN"], ...)

# This WORKS (v1.1.0 style)
terra.authentication.generatewidgetsession(providers="GARMIN", ...)

Fix: Convert your list to a comma-separated string: providers=",".join(providers_list)

Changelog from 0.0.17 to 1.0.x #58

Description

Activity

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions