Connection troubleshooting

If Beaver shows "Connection Failed", it means Beaver couldn't reach its server. In most cases the problem is between Zotero and the internet, not with Beaver's servers. This page walks through the common causes and what to try. It also gives some technical details that can help users or IT teams to resolve connection issues.

What Beaver needs to connect

Beaver connects to two services from inside Zotero:

The Beaver API at beaver-backend-258989374544.us-central1.run.app on port 443 over both HTTPS and WebSocket Secure (wss://). Beaver streams responses over WebSocket, so allowing HTTPS alone is not enough.
Supabase at *.supabase.co on port 443, over HTTPS. This is used for sign‑in.

If either of these is blocked, or if the connection is intercepted and re-signed by security software, you'll see "Connection Failed".

Most common cause: your network is blocking Beaver

Work, school, and hotel Wi-Fi networks often run a proxy, firewall, or content filter that might block the kind of streaming connection Beaver uses. This is by far the most common cause of "Connection Failed" reports.

Quick test: try Beaver on a different network. If it works there but fails on your work network, your network is the culprit.

What to do:

If you can switch networks, do so.
If you have to stay on the restricted network, ask your IT team to allow Beaver's traffic. See For IT administrators below.
If your organization requires a specific HTTP proxy, Zotero (which is based on Firefox) honors proxy settings under Edit → Settings (Zotero → Settings on macOS) → Advanced → Config Editor, in the network.proxy.* keys.

Security software interference

Antivirus, VPN, or corporate security suites sometimes intercept every secure connection your computer makes, decrypt it, and re-sign it with their own certificate. That process (often called TLS inspection or SSL inspection) breaks Beaver's connection, because Zotero doesn't trust the re-signed certificate.

If Beaver's error shows error code 1006 or error code 1015, TLS inspection is a likely cause.

What to do:

Temporarily disable your VPN or the "web protection" feature of your antivirus, and try again. If Beaver works, that program is the cause.
Add an exception for beaver-backend-258989374544.us-central1.run.app in your security software so its traffic isn't inspected.
On a corporate machine, your IT team is the right point of contact. See below.

Temporary server issues

If Beaver's error shows a code in the 1011-1014 range, the server is telling Beaver something went wrong on its side. This is almost always temporary. Wait a moment and click Retry.

If Beaver's error shows a 4xxx code, the server rejected the connection for another reason. For example, an outdated or unsupported client. Retrying may help, but if it doesn't, check that Beaver is up to date.

If it keeps failing for more than a few minutes and switching networks doesn't help, please contact us at contact@beaverapp.ai.

For IT administrators

If a colleague at your organization is having trouble using Beaver, please allow the following outbound traffic on TCP port 443:

Host	Protocols
`beaver-backend-258989374544.us-central1.run.app`	HTTPS and WebSocket Secure (`wss://`)
`*.supabase.co`	HTTPS

Requirements:

WebSocket traffic must be permitted. Beaver streams responses over wss://, not plain HTTPS. Proxies that strip or block the Upgrade: websocket and Connection: Upgrade request headers will cause "Connection Failed".
Exempt beaver-backend-258989374544.us-central1.run.app from TLS/SSL inspection. Many web filters and next-gen firewalls (Zscaler, Netskope, Blue Coat, Palo Alto, Fortinet, etc.) inspect encrypted traffic by re-signing it with an internal certificate. Zotero will not trust that certificate and the connection will fail.
No custom API endpoint or proxy setting is required inside Beaver. Beaver uses whatever proxy is configured for Zotero (Edit → Settings (Zotero → Settings on macOS) → Advanced → Config Editor, network.proxy.*).

If you need more information, please contact us at contact@beaverapp.ai.

Reading the error code

Beaver shows a numeric error code below the "Connection Failed" message. If you're emailing us for help, including this code helps us diagnose the problem.

Code	Meaning	Common cause
1005	No status received	Proxy or firewall dropping the connection
1006	Connection blocked before Beaver's server responded	Corporate/school proxy, firewall, or filter blocking WebSocket traffic; also the code that TLS/SSL inspection (antivirus, VPN, or corporate proxy) usually produces in Zotero
1008	Authentication or policy rejection	Beaver couldn't verify your account for this connection. Try again, or sign out and back in if it persists
1011	Server error	Temporary problem on Beaver's servers. Retry in a moment
1012	Service restart	Beaver's servers are restarting. Retry in a moment
1013	Try again later	Beaver's servers are temporarily overloaded. Retry in a moment
1014	Bad gateway	Temporary problem upstream of Beaver's servers. Retry in a moment
1015	TLS handshake failure	TLS/SSL inspection by antivirus, VPN, or corporate proxy. Rare in practice. This usually surfaces as 1006 instead
1002, 1003, 1007, 1009, 1010	Protocol error	Usually resolved by updating Beaver to the latest version
4000-4999	Server-defined rejection	Reserved for the server to signal other rejections. Retry, or check that Beaver is up to date

If nothing works

If you've tried a different network, checked your security software, and still see "Connection Failed", please send us a debug log so we can help:

In Zotero, go to Help → Debug Output Logging → Enable.
Reopen Beaver and reproduce the error.
Go to Help → Debug Output Logging → View Output.
Copy the log (especially any lines starting with [Beaver]) into an email to contact@beaverapp.ai, together with the error code shown in the Beaver panel or a screenshot of the error.
Disable debug logging under Help → Debug Output Logging → Disable.

We'll follow up with next steps as soon as possible.