Retool utils.openPage Not Passing Query Params: Fix It Now

If utils.openPage is not passing query params in your Retool app, your multi-page navigation is likely completely broken — and it's not your fault. A Retool platform update changed how utils.openPage handles query parameter passing, silently breaking apps that had been working fine the day before. This guide explains exactly what happened, what the fix is, and how to update every affected event handler in your app.

What Broke and Why

Retool introduced a new mechanism for passing data between pages using utils.openPage. As part of this change, the default behavior for how query params are transmitted was altered. Apps that were calling utils.openPage with a queryParams object suddenly found that the params were no longer appended to the URL — meaning any page that relied on url.searchParams to read incoming values received nothing and failed silently or crashed outright.

This affected both utils.openPage and utils.openApp. Specifically, utils.openApp dropped query params whenever the optional pageName parameter was included in the call. The root cause was that Retool added a new passDataWith option to control the data-passing method, but didn't default it to the old behavior — breaking backward compatibility for all existing event handlers.

Who Was Affected

Any Retool app using multi-page navigation with query params was impacted. Common patterns that broke include:

• Clicking a row in a Table component and opening a detail page with a record ID in the URL
• Passing url.searchParams values forward from page to page as users navigate a workflow
• Using a ListView button to open a dashboard scoped to a specific item via a UUID query param
• Any call to utils.openApp that included both pageName and queryParams

The symptom in all cases was the same: the destination URL was missing the ?key=value query string entirely, and any queries or components on the target page that depended on those params received undefined or an empty value.

The Fix: Add passDataWith to Your utils.openPage Calls

The fix is a single additional property in your utils.openPage options object. You need to explicitly tell Retool to use URL params as the data-passing method by adding passDataWith: 'urlParams'.

Before (broken):

utils.openPage('newPage', { queryParams: { scheme_id: item.scheme_id_uuid } })

After (fixed):

utils.openPage('newPage', { passDataWith: 'urlParams', queryParams: { scheme_id: item.scheme_id_uuid } })

That's it. Adding passDataWith: 'urlParams' restores the original behavior and your query params will appear in the destination URL as expected.

Step-by-Step: How to Update Your Event Handlers

• Step 1: Open the Retool app editor and navigate to each page that contains buttons, table row actions, or list item click handlers that trigger page navigation.
• Step 2: Open the event handler for each component. Look for any call to utils.openPage or utils.openApp that includes a queryParams object.
• Step 3: Add passDataWith: 'urlParams' as a property inside the options object, alongside your existing queryParams.
• Step 4: Save and test the navigation. Confirm that the destination URL includes the expected ?key=value query string after clicking.
• Step 5: On the destination page, verify that url.searchParams.yourKey returns the correct value and that any queries dependent on it are firing properly.

Temporary Workaround If You Need It Fast

If you need to unblock your users immediately while you audit all affected handlers, you can swap utils.openPage for utils.openUrl as a short-term patch. Construct the URL manually with query params embedded as a string. This isn't ideal for maintainability, but it bypasses the routing issue entirely and works reliably while you roll out the proper fix across your app.

Example: utils.openUrl('/apps/your-app-name/newPage?scheme_id=' + item.scheme_id_uuid)

When Was This Fixed in Retool Cloud?

Retool confirmed the fix was deployed to cloud in version 3.116. However, simply being on 3.116 is not enough — you still need to update your event handlers to include passDataWith: 'urlParams'. The platform fix changes the default behavior going forward, but your existing handler code needs to be explicit about the method until the default is fully restored in a subsequent release.

Key Takeaway

If utils.openPage is not passing query params in your Retool app, update every affected event handler to include passDataWith: 'urlParams' in the options object. This one-line change restores query param routing and gets your multi-page app working again. If you're managing a large Retool deployment with many pages and handlers, do a codebase search for all occurrences of utils.openPage and utils.openApp to make sure nothing is missed.