Known limitations

Port Zero installs a local certificate authority into the OS trust store and per-browser NSS databases so *.portzero.local works over HTTPS without certificate warnings. That coverage is broad but not universal. This page tracks the specific gaps found so far and the documented fallback for each.

This isn’t a general troubleshooting index — see Troubleshooting for day-to-day failure modes (curl can’t resolve a tunnel name, PZ_TUNNEL set too late, etc.). This page is specifically about browser/engine-level CA trust gaps that have an identified cause and a documented workaround.

Snap-packaged Chromium-family browsers (Brave, Chromium) on Linux

Symptom: net::ERR_CERT_AUTHORITY_INVALID for any *.portzero.local name, specifically in the Snap package of Brave or Chromium, while the native (non-Snap) package of the same browser works.

Cause: portzero trust install seeds the Snap revision’s own NSS certificate database and refreshes the system trust-store compat bundles that back it. Some Snap Brave/Chromium builds still ignore both of those locally installed trust anchors and report the Port Zero CA as an unknown issuer regardless — this is a Snap browser sandboxing/packaging quirk, not something portzero trust install failed to do.

Fallback: use the native (non-Snap) package of the same browser, or a different browser entirely. There’s no equivalent of a “trust this certificate” flag for regular end-user browsing — the workaround here is packaging choice, not a flag.

Playwright’s bundled Firefox on Linux

Symptom: a Playwright test navigating to https://*.portzero.local in the firefox project fails with a certificate-trust error, while the same test in the chromium and webkit projects succeeds, on a hosted CI runner with portzero trust install already run.

Cause: Firefox’s certificate database is per-profile, not a single shared system database. portzero trust install seeds the shared Chrome/Chromium/native-Brave store proactively, plus any existing Firefox profile directories. Playwright, however, launches its bundled Firefox against a fresh, ephemeral profile created per test run — that profile doesn’t exist at CA-install time, so it’s never seeded, and the CA is untrusted there by construction. This isn’t a bug in the CA-install logic; it’s a mismatch between “seed known profile directories” and “Playwright creates a new, unknown one every run.”

Fallback (documented, in use): set ignoreHTTPSErrors: true for the firefox project in your Playwright config.

Chromium and WebKit on hosted CI runner images

Symptom: on some hosted CI runner images, Playwright’s chromium and webkit projects both fail to trust the Port Zero local CA over https://*.portzero.local — not just the Firefox gap above.

Cause (partially identified): the daemon’s own log can show the trust-store compat-bundle refresh failing on some runner images with an “unknown error” from the underlying trust tooling. That plausibly explains WebKit, whose trust path is documented as depending on that refresh. It doesn’t explain Chromium, whose trust path is documented as depending only on the shared NSS store — Chromium’s failure on those images is unexplained and needs separate investigation.

Fallback (documented, in use): ignoreHTTPSErrors: true for the chromium and webkit projects too, alongside firefox, matching observed CI reality rather than the (currently incorrect) theoretical expectation.