Umami v3.5

Today we are releasing Umami v3.5.0.

This release brings browser error tracking to Umami, so you can investigate the problems visitors run into alongside their activity on your site. We have also made it easier to move through session replays, explore changes in your traffic, and compare reporting periods, with security and reliability improvements throughout the app.

Browser error tracking

A drop in conversions can start with something as simple as a broken button or a failed form submission. Error tracking helps you find those problems and understand which visits they affected.

To enable it, add data-errors="true" to your tracking script:

<script
  defer
  src="https://your-umami-instance/script.js"
  data-website-id="your-website-id"
  data-errors="true"
></script>

Umami automatically captures uncaught JavaScript errors and unhandled promise rejections. You can also report errors your application has already caught with umami.captureException():

try {
  await submitOrder();
} catch (error) {
  umami.captureException(error, { tags: { feature: 'checkout' } });
}

The new Errors page under Monitoring groups errors into issues, with stack traces, occurrence counts, affected visits, and when each issue was first and last seen. You can search and filter by release, environment, browser, and page path, then resolve, ignore, or reopen issues as you work through them.

Each occurrence is linked to its session, so you can see what the visitor did before the error. If a replay was recorded, you can watch it for more context. Add data-release and data-environment to your script to label errors with your application version and environment, making it easier to investigate problems after a deploy.

We recently introduced error tracking on Umami Cloud. With v3.5, self-hosted users can run it on their own infrastructure too.

Move through replays faster

Reviewing several recordings is now easier. The replay player has previous and next controls, with left and right arrow keyboard shortcuts, so you can move between recordings without returning to the list each time.

Replay lists also show distinct visitor IDs when available. If you use umami.identify() to identify visitors, this helps you find the recordings associated with a particular user.

Better date selection and comparisons

You can now click a bar in a website chart to zoom into its date range. When you spot an unusual day or hour, you can go straight to that period to investigate.

Custom date selection uses a single two-month calendar, making it easier to choose a range that crosses a month boundary. We have also improved chart alignment, timezone handling, and daylight-saving transitions so comparisons stay consistent across reporting periods.

When comparing an ongoing period, Umami now uses the equivalent elapsed portion of the previous period. For example, a week in progress is compared with the same elapsed window of the previous week, giving you a more useful view of how performance is changing.

Retention reports have also been refined. Cell shading is relative to the highest visible value, making differences between cohorts easier to spot, and cohort dates now display correctly across timezones.

Security and access

New self-hosted installations now require changing the seeded administrator password before continuing. Password changes have also moved to Settings → Security, alongside the other account security controls.

Required two-factor enrollment is enforced on the server, with stronger checks against concurrent verification attempts and code reuse. Team permissions and API key route checks have also been tightened.

Shared links now check the current share settings on each request, so deleting a share or changing its permissions takes effect for existing links. Shared boards also have stricter limits on access to raw event, session, revenue, and realtime activity data.

More improvements

This release includes a range of smaller changes:

• Navigation and preferences: access team websites from the website switcher outside a team, open the dashboard from mobile navigation, and choose a 12- or 24-hour clock.
• Sessions and realtime: see referrers in Session Overview and active visitor indicators in the realtime activity log, with fixes for session resets and identity attribution.
• Performance: faster attribution, funnel, and paginated queries, plus more accurate performance measurements for background tabs and prerendered pages.
• Heatmaps: fixes for Safari overlays, snapshot sizing, and tracking inside preview frames.
• Filtering and search: fixes for custom wildcard selections, missing values in negative filters, and search text being overwritten by delayed navigation.
• Reliability: fixes for Redis-backed login sessions expiring during active use, stale website, link, and pixel caches, and board ownership when transferring a website.

For developers, the tracker and recorder can now read configuration from window.umamiConfig, with script attributes taking precedence. Analytics APIs accept optional period values such as today, 24h, 7d, and 30d, and website event responses include visitId. This release also adds error tracking endpoints, refreshes API client types, and corrects event-filter handling in MCP tools.

Self-hosters also gain more control over session salt rotation and client IP detection, including a TRUSTED_PROXIES setting for deployments behind multiple proxies. Client-provided session salts and tracker salt rotation require enabling ENABLE_CLIENT_SALT on the server.

Upgrading

If you self-host Umami, review these requirements before upgrading:

• Set APP_SECRET explicitly. Falling back to DATABASE_URL is no longer supported.
• Use Node.js 20.19 or later.
• Apply the database migration. This release includes the PostgreSQL migration 27_add_error_tracking.
• Update integrations that use /api/config. The public endpoint has been removed.

See the full release notes and changelog for all changes and upgrade details.

Thank you

Thank you to everyone using Umami, contributing code, reporting issues, and sharing feedback. Your contributions help us improve the tools you use every day and make it easier to understand what is happening on your site.