Website issues you could encounter

Polypane is really good at surfacing issues with websites. For example with our debug tools, outline panel and accessibility panel.

A key thing to realize is that there are certain issues that only happen in, or are more severe because of, multiple panes. Websites are frequently coded in such a way that one session requests one page one time, but with Polypane, one sessions requests a page multiple times, potentially with different device capabilities.

This can catch people off guard, thinking Polypane is not working correctly when it is actually surfacing incorrect assumptions or issues in their website.

To get a better understanding of the implications this has, please read our docs on the mental model of Polypane's browser contexts. Many of the issues listed below are a direct result of this.

Login/Logging in on websites not succeeding

Some sites prevent users from logging in from multiple panes at once for various reasons:

• They dont allow multiple login attempts,
• They have a login cooldown timer,
• They use a CRSF token or 2FA code that is only valid for a single login attempt,
• They automatically log you out when using different user agents
• ...or other mitigation strategies

All of these will make it look like Polypane can't log into a website. 9 out of 10 times this is remedied by logging in using a single pane, like in focus or full layout, and then going back to multiple panes.

If that doesn't work, you can log in using the Browse panel and refresh the panes. Since the session is shared across all panes and the browse panel, this should log you in everywhere.

log in to websites using SSO, oAuth or login redirection

To log in to sites using federated login, similarly switch to the focus or full layouts or log in using the browse panel. Polypane syncs the session across all panes, so after a reload you'll be logged in everywhere.

The reason for needing this is due to how federated logins like SSO or oAuth work:

• Many SSO or oAuth solutions depend on multiple redirects and POST requests. If Polypane syncs these redirects during the process, this can interrupt the redirection flow and cancel it.
• Many SSO or oAuth solutions see multiple simultaneous logins, or logins with different user agents, as a risk and will abort the sign-in process.

While Polypane prevents form submissions from happening in multiple panes, federated logins are often instantiated by javascript, which we can not catch. When this happens in multiple panes, multiple different popups might get opened, or the site will generate and invalidate multiple CSRF tokens (one by one for each request) which can all cause logins to fail.

There is no way to work around this while showing the page multiple times and syncing interactions. Luckily, the solutions mentioned above are robust and easy.

Non-persistent authentication

If your site logs you out on every refresh, Polypane can unexpectedly log you out when it needs to sync up the navigation state between panes.

Sessions, user interactions and navigation are all synced between panes. This means that when you're logged in anywhere, you're logged in everywhere. It makes sure that panes all get the time needed to navigate on their own as a result of a synced user interaction so syncing happens naturally.

However as a last resort, it updates the URL of panes that have not navigated yet. If this subsequently triggers a log out event, that will then get synced to all other panes as well.

The only way to work around that is to prevent logging out when Polypane is detected or finding where the click events are not correctly synced (a common issue is using different UI elements on different screen sizes and making sure you use the same UI elements across sizes.

Performance issues

Polypane runs the same code in each pane so performance bottlenecks are quicker to show.

Roughly put, Polypane needs the same amount of resources for each pane as Chrome needs for a single tab. It's essentially rendering multiple full Chrome tabs at the same time, with the CPU and memory requirements that brings, and without the ability to throttle all the non-active tabs (because all panes need to be kept in sync).

This means that while your site might perform well on your fast computer in a single tab, when that same code is executed 3, 4 or 5 times, bottlenecks start to appear.

Those bottlenecks were always there, Polypane just enlarges them. They will also be there when a user has other resource intensive tabs open (like playing a video on YouTube) or has your page open on a less powerful device than yours.

If you notice performance issues, try to run Polypane with this docs page URL, and see if the performance issues persist.

If they get resolved, please tell us the URL so we can figure out what that bottleneck is and either help you improve your website or help us improve our application. We really appreciate this.

There are ways to improve performance in Polypane, check out the Performance docs for tips on optimizations you can do.

Rate limited APIs

Each pane in Polypane requests its own resources, so you download them for each pane separately. A rate limited API reaches that limit faster the more panes you have. This is essential for emulation, where your server might send different resources depending on the user agent and other properties. But if your server limits the number of calls you can make, or you have a rate-limited API you use, Polypane will reach that limit faster the more panes you use.

If you depend on an API with rate limiting for your development work we highly recommend you replace it with a mock server, caching proxy or disable it.

The same goes for rate limits and connection limits on your own server, CDN or firewall, which is covered in the next section.

Connection limits, WAFs and abuse prevention

Rate limits on your own server, CDN or firewall are similar to rate limited APIs, but they're easier to miss because you might not have set them up yourself: your host, CDN or a security plugin may have enabled them by default.

Symptoms look like this:

• One or two panes load fine and the rest show a 429 ("Too many requests"), 503 or a connection reset,
• A Cloudflare (or other WAF) challenge, captcha or block page appears in some panes but not others,
• Panes hang halfway through loading, with assets missing,
• Your IP gets temporarily banned after a few minutes of testing and the site stops working for you in every browser.

This happens because each pane requests its own resources, so a single page load in a 4 pane workspace is 4 page loads and 4 sets of assets (depending on your caching settings), starting at roughly the same time. Connection limits (the number of simultaneous connections from one IP) and rate limits (requests per time window) are often counted per IP, so Polypane can hit a limit roughly N times faster with N panes.

This isn't abusive traffic. It's comparable to opening the same site in several tabs and refreshing them around the same time. The difference is that Polypane deliberately makes this happen in one action because each pane is an independent browser context.

How to prevent it

There's multiple ways to solve this, in order of preference:

1. Allowlist your own IP on the limiter, so your development traffic is never counted. Instructions for common tools are below.
2. Turn the limits off in your development and staging environments. Rate limiting is a production concern, and there's rarely a reason to run it locally or on a staging server.
3. Raise the burst allowance rather than the sustained rate. Most limiters allow a short burst above the limit before they start rejecting. Multiplying that burst by the number of panes you have is usually enough.
4. Use fewer panes while working on the affected pages, or use focus layout for that part of your work.

To find the IP you need to allowlist, open whatismyip.com in Polypane's Browse panel, or run curl ifconfig.me in your terminal.

You can also allowlist based on the Polypane user agent instead of your IP, see Detecting Polypane for the user agent string. Keep in mind that emulation overwrites the user agent, so it won't match in every pane. Don't do this in production though, since it would allow anyone using Polypane to bypass your limits.

Cloudflare

Cloudflare limits can come from Rate limiting rules, WAF custom rules, Bot Fight Mode or "I'm Under Attack" mode. Some bot-protection systems may treat Polypane differently from a normal Chrome browser, particularly when combined with high request rates.

• Skip specific rules: create a custom rule with the Skip action and expression (ip.src eq YOUR.IP.HERE), and check the rule types you want skipped (rate limiting rules, managed rules, etc).
• Allowlist your IP entirely: go to your domain, then Security → Security rules → Create rule → IP access rules. Enter your IP address, set the action to Allow and apply it to the current website. This exempts you from IP-based limits and challenges.
• Exclude yourself from one rate limiting rule: edit the rule's expression and add and ip.src ne YOUR.IP.HERE to it.
• If you're being challenged rather than blocked, check Security → Settings for Bot Fight Mode and the Security Level, and turn off "I'm Under Attack" mode while developing.

nginx

nginx limits come from limit_req (requests per second) and limit_conn (simultaneous connections). Use a geo block to give your own IP an empty limit key, which excludes it from the zone:

geo $limit {
  default        1;
  YOUR.IP.HERE   0;   # your IP: not rate limited
}

map $limit $limit_key {
  0 "";
  1 $binary_remote_addr;
}

limit_req_zone  $limit_key zone=reqs:10m rate=10r/s;
limit_conn_zone $limit_key zone=conns:10m;

server {
  limit_req  zone=reqs burst=40 nodelay;
  limit_conn conns 20;
}

If you'd rather not allowlist, increase the burst and concurrent-connection limits enough to accommodate the number of panes you're using.

Apache

• mod_evasive: add your IP to the allowlist with DOSWhitelist YOUR.IP.HERE (wildcards like 198.51.100.* also work) in your mod_evasive.conf. Also consider raising DOSPageCount and DOSSiteCount, which are low by default and count all panes together.
• mod_qos / mod_security: see the ModSecurity section below.

fail2ban

fail2ban bans your whole IP, so a false positive takes your site down for you completely. Add your address to ignoreip in the [DEFAULT] section of jail.local:

[DEFAULT]
ignoreip = 127.0.0.1/8 ::1 YOUR.IP.HERE

Then reload with fail2ban-client reload. If you've already been banned, unban with fail2ban-client set <jailname> unbanip YOUR.IP.HERE.

ModSecurity / OWASP Core Rule Set

Disable the rule engine for your own IP, early in the rule chain (a low rule ID, before the CRS rules run):

SecRule REMOTE_ADDR "@ipMatch YOUR.IP.HERE" \
  "id:1000,phase:1,pass,nolog,ctl:ruleEngine=Off"

AWS WAF

Create an IP set containing your address, then add a rule with the Allow action that matches it and give that rule a lower priority number than your rate-based rule.

Express / Node (express-rate-limit)

Use the skip option:

const allowlist = ['YOUR.IP.HERE'];

rateLimit({
  windowMs: 60 * 1000,
  limit: 100,
  skip: (req) => allowlist.includes(req.ip),
});

If your app is behind a proxy, make sure app.set('trust proxy', ...) is configured, otherwise every request looks like it comes from the proxy and the allowlist will never match.

Laravel

Return an unlimited rate limit for your own IP in the rate limiter definition (in AppServiceProvider or RouteServiceProvider):

RateLimiter::for('api', function (Request $request) {
    if (in_array($request->ip(), ['YOUR.IP.HERE'])) {
        return Limit::none();
    }

    return Limit::perMinute(60)->by($request->ip());
});

WordPress (Wordfence, Limit Login Attempts, iThemes/Solid Security)

• Wordfence: Wordfence → All Options → Allowlisted IP addresses, and add your IP. Also check "Rate Limiting" in the same screen. The defaults ("throttle crawlers/humans crawling more than X pages per minute") are low enough that a few panes can trip them.
• Limit Login Attempts Reloaded: add your IP under Safelist in the plugin's settings.
• Solid Security (formerly iThemes Security): add your IP to the Allow List under Security → Settings → Global Settings.

Hosting platforms

• Vercel: check the Firewall tab of your project for rate limiting rules and Attack Challenge Mode. You can add a bypass rule matching your IP.
• Netlify: rate limiting is configured per-domain in the Traffic rules section. Exclude your IP there, or disable the rule for your test environments.
• Managed WordPress and shared hosting (Kinsta, WP Engine, SiteGround, and similar) often apply undocumented connection limits at the edge. If you're seeing 429s you can't trace to your own config, ask their support to allowlist your IP for your staging environment.

If your limiter isn't in this list and you've found a way (or are looking for a way) to allowlist Polypane, please tell us about it so we can add it.

Each pane in Polypane contributes to your page load statistics

Because Polypane downloads and executes your page for each pane, any anayltics tool will record each visit as well which could lead to quite a spike in your stats after using Polypane.

In general it's best practice to configure your analytics tools to ignore your own IP address or otherwise tell it to ignore visits from Polypane. You could also configure your site/app such that the analytics script is only ever loaded in production and not in development.

Filtering Polypane in your analytics tools

You usually want to filter out visits from Polypane in your analytics tools to make sure the data in there is not skewed by your own testing. Many analytics tools have built-in features to help you filter out visits from Polypane which you can find below.

Simple Analytics automatically filters visits from Polypane out of the box. So if you use Simple Analytics you don't have to do anything.

For other analytics tools, their capabilities for filtering Polypane depend on the features of the tool. Here we outline some:

• Plausible Analytics: filter out your own visits by adding a localStorage entry with the key plausible_ignore and value true. You can do this in the Storage panel where you can also pin the value so it will persist.
• Umami: filter out your own visits by adding a localStorage entry with the key umami.disabled and value 1. You can do this in the Storage panel where you can also pin the value so it will persist.
• Fathom Analytics: filter out your own visits by adding a localStorage entry with the key blockFathomTracking and value true. You can do this in the Storage panel where you can also pin the value so it will persist.
• Matomo: You can add Polypane to the global list of ignored user agents in the Website settings. You can find the user agent string for Polypane in our docs on Detecting Polypane.
• Google Analytics: Create a new segment or filter in Google Analytics that excludes visits where the user agent contains "Polypane".

If you use another analytics tool, check if it has the ability to filter out visits based on user agent or a custom flag, and use the user agent string for Polypane to filter out those visits. If you found a way to filter out Polypane in your analytics tool and it's not in this list, please tell us about it so we can add it!

Not syncing between panes

The most common reason for input not syncing between panes is that you're not using the same elements across sizes, or that the same element isn't available in all panes (for example, with HTML that is conditionally added through JS)

Polypane syncs events on the same elements across panes. If those elements aren't available, no syncing is possible. There's usually two common reasons for this:

• Duplicated UI for different screen sizes: for example, a mobile menu and normal menu that are different elements.
• Conditional rendering: elements that are only added or removed to the DOM after a certain event, like a click or a scroll.

When you click the normal menu in one pane, that doesn't exist in the other pane, so there is no element for the click to sync to in the other pane. Rather than building and maintaining two sets of components, it's better to build one set of components and use media queries to style them appropriately for the viewport size. This has additional benefits for maintainance, performance and accessibility.

When you have DOM that you add and remove on click or hover, Polypane again would try to sync to an element that doesn't exist in the other pane. Rather than manipulating the DOM directly, you can use CSS classes to show and hide elements. This has many additional benefits for discoverability, SEO, error recovery and more.

Mobile rendering

Pages might look fine in Polypane but are zoomed out on actual mobile phones. This is because Polypane by default will use "desktop" rendering. You can use the emulation options to toggle to mobile rendering.

Desktop rendering is faster and will make your site look responsive even if you don't set the right viewport meta tag.

Mobile phones however, have to support the entire internet, including sites that were never optimized for mobile devices in the first place. So when a viewport tag with the right value is not available, It will pretend it's much wider and then zoom out the site to fit.

When you're missing a viewport tag, mobile devices will think you didn't make a responsive website, and render it differently.

Tldr: Stick to our responsive design ground rules to not be surprised when testing on actual devices.

Domains not forwarding correctly

Forwarding from HTTP to HTTPS (upgrading) or from the bare domain to www. is something that has to be configured correctly on the server. Incorrect configuration can lead to behavior where, if your SSL certificate does not cover all (sub)domains, one of the urls will actually cause an SSL certificate error, or attempt to redirect to an unconfigured domain.

Unfortunately, having an incorrectly configured server happens so often that modern browsers like Chrome and Firefox detect these issues and will fix them for you, without confronting the end user with the issues causes by an incorrectly configured server.

Polypane is a browser for developers, so it does not compensate for incorrectly configured servers. It will either not forward, or show an SSL error, in situations where Chrome won't.

If you need to explain this to back-end developers or devops, and they point to Chrome working, you can ask them to use Polypane or test all variations of the URL with curl, and they'll see which one fails soon enough.

Non standard navigation

If you use non standard navigation, Polypane has no way of knowing it should sync anything between panes.

Polypane can accurately sync regular HTTP navigation as well as the History and Navigation APIs.

This means that any routing solution that uses the History API (React router, Astro, Next, Vue router, Reach router, Angular router, etc) works really well in Polypane. In fact this website is built using Gatsby and its built-in routing.

When you don't use the browser-supported navigation methods however, Polypane can only depend on input syncing to maintain the state between panes. Equally as important, assistive technologies will also have a tough time keeping your visitor informed of where they are, meaning you might be creating an accessibility issue for your users.

We highly recommend you use a modern and battle tested routing solution, as it will massively improve the user experience.

Third party scroll syncing issues with Browsersync or Ghostery

Tools like Browsersync or Ghostery leads to a janky experience in Polypane because Polypane syncs faster than those tools.

Polypane already syncs scrolling, navigation and input events. Polypane does this in-process, but tools like Browser-sync and Ghostery use a local webserver. This makes them (slightly) slower than Polypane. Because of that these tools can actually reset your scrolling: they're syncing state from a moment ago while Polypane has already synced the next scroll event, so they cause your site to "scroll back". It's a situation where milliseconds matter and the extra round-trip to a server is enough to get the wires crossed.

When Polypane detects that you're using Browser-sync's scroll sync feature the built-in scroll syncing is disabled. We recomment that when you use these tools, you turn their syncing features off. For Browser-sync, it's called "ghost mode".