Why Collabora Online connection errors in Nextcloud happen and where to start
When Nextcloud loads but the editor fails with an unexpected connection error, or the document never renders, the fault almost always sits in one of three hops that the browser and both servers must complete in order. Nextcloud does not render the document itself. It hands the browser a Collabora discovery URL, which tells the client where the Collabora Online server is and which document formats and actions it accepts. The browser then opens a WebSocket connection directly to Collabora. Collabora, in turn, calls back to Nextcloud over WOPI to fetch the file and to check the user's access token. A failure can therefore sit in the discovery step, in the browser-to-Collabora WebSocket path, or in the Collabora-to-Nextcloud WOPI callback. The error message rarely tells you which one, so the first task is to isolate the hop before changing any configuration.
This page walks through that isolation in order: checking the capabilities and discovery URL that Nextcloud advertises, confirming that the Collabora server URL uses the same protocol as the Nextcloud installation (the Nextcloud administration manual recommends HTTPS for both), testing for protocol mismatches, and then examining firewalls, reverse proxy WebSocket rules and the logs on both sides. Work from the browser developer tools toward the servers: the network trace shows which URL the editor requested and whether the WebSocket upgrade succeeded, while the Collabora and Nextcloud logs show what each side received. Keep a record of the exact Collabora Online and Nextcloud versions in use, since the release notes for each branch can change proxy or WOPI behavior. Confirm your version numbers against the Collabora Online release notes before you act on a fix.
DeployOpen scopes this work as a fixed engagement when a team wants an outside engineer to diagnose the failing hop, correct the configuration in the client's own infrastructure, and document the result for the operations team. Scope usually covers reproducing the failure, collecting logs and traces from each side, correcting the discovery, proxy and network settings, and verifying that documents open and save for representative users. It does not usually cover rebuilding the platform. Before you request a quote, confirm who can change the reverse proxy, firewall and DNS records, whether the environment has a change window, and whether the Collabora server is a dedicated instance or the built-in CODE app, because the diagnostic path differs for each.
Triage sequence: confirm discovery, then the WOPI path, then the WebSocket
This sequence isolates a connection failure to one layer at a time, so the team fixes the component that is actually broken instead of changing settings across the stack. Each step ends with a result that either clears the layer or points to the next place to look.
Check the Nextcloud Office admin page
A Nextcloud administrator opens the Office settings in the Nextcloud admin interface and reads the status of the configured Collabora Online server. The check passes when the page shows the Collabora server as reachable and no connection warning is displayed. If the page reports the server as unreachable, record the exact URL shown there, because every later step must test that same address. Confirm the URL uses the same protocol as the Nextcloud installation, preferably HTTPS, as the Nextcloud administration manual recommends. Do not change any other setting until this check result is recorded.
Fetch the Collabora discovery document
From a machine on the Nextcloud network, an operator requests the discovery document from the Collabora Online URL, using the path that Collabora publishes for WOPI discovery. The check passes when the server returns the document with a success response and lists the file types it supports. Next, compare the URLs inside the document with the server URL configured in Nextcloud. A mismatch in host name, port, or protocol, such as an HTTP URL where Nextcloud expects HTTPS, is the most common cause of failed editing at this stage. Save the response so the team can compare it after each change.
Confirm DNS and firewall paths both ways
The network team confirms that the Nextcloud server can reach the Collabora host, and that the Collabora host can reach the Nextcloud host, on the ports each side uses. The check passes when name resolution returns the expected address from each server and a connection attempt completes on the required port. Reverse proxies, load balancers, and firewall rules often differ between the public address that browsers use and the internal address that servers use. Record both paths. If a path fails, fix the network rule before testing application settings, since application logs will not show a clear cause for a blocked connection.
Confirm the WOPI callback from Collabora
Open a test document from Nextcloud and watch the Nextcloud and Collabora logs during the open attempt. The check passes when Collabora requests the file from Nextcloud through the WOPI endpoint and Nextcloud returns the file without an authorization or host error. If Collabora logs a refused request, check whether the Nextcloud server address is covered by the WOPI allow list on the Collabora side, and whether Nextcloud restricts WOPI requests to known Collabora IP addresses. Those restrictions need to match the current network path, so confirm them after any address change. Treat a refused request as an allow list problem, not a browser problem.
Verify the browser WebSocket upgrade
In the browser developer tools, open the network panel, load the same test document, and filter for WebSocket connections. The check passes when the connection shows an HTTP 101 Switching Protocols response and stays open while the document loads. A failed upgrade usually points to the reverse proxy: confirm that it forwards the Upgrade and Connection headers and that it routes WebSocket traffic to the Collabora server, not only to the discovery path. If the proxy passes WebSocket traffic only for some paths, the document may appear to load but fail when editing starts. Record the proxy setting you changed, if any.
Compare logs on both sides
The operator reviews the Nextcloud log and the Collabora Online server log for the same test session, matching timestamps to the failed attempt. The check passes when both logs show a complete session with no unexplained errors, and the document opens in the editor. If the logs disagree, the layer where the first error appears is the one to fix. Confirm the log level is high enough to show request-level errors, and avoid copying document content into tickets when you share log excerpts. Once the document opens reliably with a second test user, the connection path is verified.
Matching the symptom to the likely cause
This error appears when Nextcloud cannot establish the session with the Collabora Online server, or when the browser cannot reach the Collabora Online URL that Nextcloud returned. The most common causes are a protocol mismatch between the two URLs, a hostname that does not resolve from the browser, or a proxy that blocks the WebSocket connection. Start by confirming which URL Nextcloud is using, because the error often comes from a value set once during installation and never revisited.
- Protocol mismatch: The Nextcloud administration manual recommends using the same protocol for the Collabora server URL as for the Nextcloud installation, preferably HTTPS. A plain HTTP Collabora URL on an HTTPS Nextcloud site is a frequent cause.
- Hostname and DNS: Confirm that the Collabora hostname resolves from the user's network and from the Nextcloud server. A name that works only inside one network segment will fail for everyone else.
- Reverse proxy WebSocket rules: Check that the proxy forwards the Upgrade and Connection headers for the WebSocket path. Without them the editor session cannot start.
- Discovery and capabilities: Open the Collabora discovery endpoint in a browser and confirm it returns XML and the expected hostnames.
Check the Nextcloud admin settings for the Collabora URL first, then the discovery response, then the proxy configuration.
Here the editor opens, shows the document briefly, then drops to a disconnected state or reloads. The session was established, so the basic routing works, but a persistent connection fails after the handshake. This pattern usually points to WebSocket headers being stripped or timed out by an intermediate proxy, or to a firewall that closes idle long-lived connections.
- Stripped WebSocket headers: Some proxies accept the initial request but drop the upgrade on the live connection. Compare the proxy configuration with the Collabora documentation for your ingress.
- Proxy timeouts: Idle timeouts shorter than an active editing session cause disconnects during quiet periods. Review read and send timeouts on the proxy.
- Firewall or inspection devices: Security appliances that inspect or rewrite traffic can break WebSocket frames. Test with the same path from a client network segment.
- Load balancer affinity: If requests for one document reach different backends, the session is lost mid-edit. The Helm chart README states that load balancers must route by the WOPISrc parameter.
- Browser console and proxy logs: Look for close codes and upstream timeout messages at the moment of disconnect.
Correlate the disconnect time with proxy access and error logs before changing any timeout values.
Mixed content warnings appear when a secure Nextcloud page loads resources or connects to endpoints over an insecure scheme. The browser may block the editor frame, show a warning banner, or refuse a WebSocket connection to a plain address. These warnings are often a configuration mismatch rather than a network fault, which makes them quick to fix once the source is found.
- Insecure Collabora URL: An http:// Collabora address configured in an https:// Nextcloud site triggers blocking by the browser. Update the Collabora server URL to match the Nextcloud scheme.
- Forwarded protocol headers: If the proxy does not pass the original scheme, the application may generate http links. Confirm that forwarded protocol headers are set and that the application trusts the proxy.
- Certificate problems: A certificate that does not cover the hostname in use causes the browser to reject the connection, sometimes with a message that looks like a protocol error.
- Stale cached settings: Clear the browser cache after changing URLs, since an old discovery response can persist.
- Browser developer tools: The console lists each blocked request and its scheme, which identifies the exact setting to change.
Check the scheme and hostname in the browser console first, then the forwarded headers, then the certificate chain.
When some users can edit and others cannot, the server is probably running, so the cause lies in the path those users take or in their account settings. Typical differences are network location, VPN or proxy routing, DNS resolvers, browser versions, and group permissions in Nextcloud Office. Comparing a working user with a failing user is the fastest way to isolate the difference.
- Network path: Users on a particular subnet, VPN, or remote site may resolve a different address or reach a firewall rule that blocks the Collabora port.
- DNS split horizon: Internal and external resolvers may return different records for the same hostname.
- Group restrictions: Nextcloud Office can limit which groups use the editor or can edit rather than only view. A user outside those groups sees a different result.
- Browser and extensions: Older browsers or privacy extensions that block WebSocket traffic affect only the users who run them.
- Source addresses: If the WOPI allow list only covers some addresses, requests from other networks are refused.
Ask affected users for their network and browser, then compare their resolved address and group membership with a working account.
Configuration settings to check and when each fits
This table compares the Nextcloud and Collabora settings that most often cause 'unexpected connection error' and documents that will not load. Read each row as a checkpoint: confirm the setting, confirm the value matches how users and servers actually reach each other, then move on. Exact key names and menu labels vary by Nextcloud and Collabora version, so confirm them in your own installation before editing.
| Setting | Where it lives | When it fits | Common mistake |
|---|---|---|---|
| Collabora server URL in Nextcloud Office | Nextcloud admin settings, Nextcloud Office section | Set to the address users' browsers reach Collabora on, served through the same protocol as Nextcloud | Left as a container or internal hostname that browsers cannot resolve |
| Protocol of the Collabora server URL | Same Nextcloud Office field as the server URL | Match Nextcloud exactly, preferably HTTPS on both sides | Nextcloud served over HTTPS while Collabora URL is HTTP, causing mixed-content blocks |
| WOPI allow list | Collabora server configuration (confirm the exact key for your version) | Admit only the IP addresses of the Nextcloud servers that call Collabora | Allow list written with old addresses after a load balancer or NAT change |
| Public and internal URL split | Nextcloud config and Collabora server settings (confirm key names) | Browsers use a public address while Nextcloud calls Collabora over an internal network | Nextcloud calls the public name, which hairpins or fails from inside the network |
| WOPI host and aliasgroup settings | Collabora server configuration (confirm key names for your version) | Nextcloud is reached under more than one name, such as an internal and a public hostname | Only one name is listed, so requests from the other name are refused |
| Reverse proxy WebSocket forwarding | Proxy configuration in front of Collabora | Editing sessions need a persistent WebSocket connection through the proxy | Upgrade and Connection headers are not forwarded, so the editor loads but cannot save or sync |
| Certificate trust between servers | Operating system or container trust store on the Nextcloud host | Nextcloud must trust the certificate presented by the Collabora URL | Self-signed or internal CA certificate not installed on the Nextcloud host |
| Group limits for editor access | Nextcloud Office admin settings | Restrict which groups can open or edit documents during rollout | Groups limited to view only, so users report that editing is broken |
Reverse proxy rules that break WebSocket sessions
Most connection errors that appear only after Collabora Online sits behind a proxy come from a handful of rules: WebSocket upgrades, timeouts, body sizes, path prefixes and routing. Each rule below is a point where the proxy can silently break an editing session that worked when accessed directly.
WebSocket upgrade headers
Collabora Online keeps the editing session open over a WebSocket connection, so the proxy must pass the Upgrade and Connection headers through to the Collabora server instead of closing the request as ordinary HTTP. A document may open, then freeze or show a connection error once editing starts. Check that your Nginx, HAProxy or OpenShift Router configuration forwards these headers on the Collabora location, and test by opening a document and typing in it from a browser that is not on the internal network.
Long read timeouts for editing
Default proxy timeouts are often set for short web requests, while an editing session can stay idle for long periods and then send traffic again. An idle WebSocket that the proxy closes looks to the user like a lost connection. Raise the read and send timeouts for the Collabora path to values your operations team agrees on, and confirm that load balancers in front of the proxy apply the same idle limits. Record the values in your change log so a later hardening change does not reset them.
Request body size limits
Saving and inserting large files sends sizeable request bodies through the proxy. If the proxy limits body size more tightly than Nextcloud allows, uploads or saves fail with an error that appears to come from Collabora. Compare the proxy limit on the Collabora hostname with the file size you expect users to work with, and check the Nextcloud upload limit as well. Test with a large file that users actually handle, not a small sample.
Path prefixes Collabora serves
Collabora Online serves its discovery information, editing pages and WebSocket endpoints under specific URL paths. If the proxy rewrites or strips a prefix, or sends only the root path to Collabora, Nextcloud receives a discovery response it cannot use and the editor never starts. Confirm that every prefix Collabora serves reaches the backend unchanged, and compare the discovery URL with what the proxy returns from outside your network. Use the same protocol, preferably HTTPS, as the Nextcloud installation.
Routing by WOPISrc
When more than one Collabora server runs behind a load balancer, every user editing the same document must reach the same server. The Helm chart documentation states that load balancers must route by the WOPISrc parameter for this reason, and that horizontal pod autoscaling is disabled because scaling breaks collaborative editing. Without this rule, two users may land on different servers and see a document that will not load or will not sync. Confirm the routing key in your load balancer and test with two sessions on the same document.
Ingress options named in the chart
The Collabora Helm chart documentation names Nginx, HAProxy and OpenShift Router as supported ingress controllers. Each has its own syntax for WebSocket support, timeouts and header handling, so a rule that works in one often needs a different form in another. Record which controller you run, copy the rules from your own tested configuration rather than a generic example, and ask your platform team to confirm the controller version before you change any rule.
Reading logs on the Nextcloud and Collabora sides
Start with the logs on both sides of the WOPI exchange, because an "unexpected connection error" in Nextcloud usually means the request failed somewhere between the two servers, and only one side will show why. On the Nextcloud side, raise the log level for the Office app and the general Nextcloud log only for the test window, then pull entries covering the minutes when a user opened a document and failed. Confirm the log file location, the log level setting and the format for your installation, since these depend on how Nextcloud was deployed. On the Collabora side, the server process writes its own log through coolwsd. Confirm where your packaging or container writes that output and which level it runs at before you rely on it, because the default level can omit the WOPI and connection messages you need.
Correlate the two logs by time first, then by identifier. Clock skew between the Nextcloud host, the reverse proxy and the Collabora host can make matching entries look unrelated, so check that all three use synchronized time before comparing timestamps. Then match on the document or request identifiers that appear in both logs, such as the file ID, the WOPISrc value or the request path, and note which side logged the failure first. A Nextcloud entry that shows the editor URL was issued, followed by no matching WOPI call on the Collabora side, points at network reachability or the proxy. A WOPI call that Collabora rejected points at the allow list or protocol configuration covered elsewhere on this page.
Keep document content out of tickets. Logs at debug level can include file names, paths, user names and sometimes fragments of request bodies, so before you attach anything to a vendor or internal ticket, strip file names and paths that reveal sensitive content, replace user identifiers with pseudonyms, and share only the lines around the failing request. Store the raw extract in your own restricted location and set a date to lower the log level again once the test is complete. Ask your Collabora support contact or Nextcloud administrator which fields they need before you send anything, so the extract contains only what they can use.
Questions operators ask before bringing in outside help
How long does it take to isolate a Collabora Online connection error?
Isolating a connection fault usually takes as long as it takes to confirm which side is failing, and that depends on how many components sit between the browser and the Collabora server. The main drivers are the number of hops (reverse proxy, load balancer, firewall, DNS), whether logs on both the Nextcloud and Collabora sides are accessible, and whether the fault reproduces on demand. Faults that appear only after a network or certificate change tend to take longer because the working configuration has to be reconstructed. Ask any provider for the steps they will take to separate discovery, WOPI reachability and WebSocket problems, and for the access they need to logs and configuration before work starts.
Can our own team resolve a Collabora Online connection error without outside help?
In many cases, yes. The Nextcloud administration manual recommends that the Collabora server URL use the same protocol as the Nextcloud installation, preferably HTTPS, and that WOPI requests be restricted to the Collabora server IP addresses. Checking those settings, the discovery URL and the reverse proxy WebSocket rules is within reach of a team that already runs Nextcloud and its proxy. Outside help becomes more useful when the fault spans several teams (network, identity, proxy), when logs point to a version mismatch, or when the same fault returns after each fix. Decide on this after a first pass through the logs on both sides.
What information do we need to provide for a troubleshooting engagement?
Work goes faster when you can supply the following before the first session:
- Exact versions of Nextcloud, the Nextcloud Office or Collabora integration, and the Collabora Online server, including the branch (for example 25.04 or 26.04)
- The Collabora server URL and the WOPI host URL as configured in Nextcloud, plus the discovery URL those servers report
- Reverse proxy configuration for both services, including the WebSocket upgrade rules
- A simple network diagram showing DNS names, load balancers, firewalls and which IP addresses reach the Collabora server
- Nextcloud and Collabora logs from a failed attempt, with timestamps, and the time zone used
Sanitize credentials and document content before sharing. Ask the provider how they will handle the logs you send.
What does a fixed-scope troubleshooting engagement cover?
A fixed-scope engagement covers the systems, symptoms and deliverables named in a written scope agreed before work starts. For connection errors, a typical scope would name the affected Nextcloud and Collabora servers, the symptom being fixed (for example, an unexpected connection error when opening a document), the checks to perform across capabilities, discovery, WOPI reachability, firewall and proxy, and the written record of findings and changes. Items outside that list, such as a major version upgrade or a new integration, would be a separate scope. Ask for the diagnostic steps, the change record and the handover notes to be named in the scope document.
Is CODE suitable for a production Collabora Online deployment?
No. Collabora describes CODE (Collabora Online Development Edition) as suited to testing, home use or small teams and not recommended for production. CODE is released on average once a month as a rolling release, so it changes often and offers no long term support track. Production deployments that need a stable branch, signed security updates and a service level agreement are the purpose of the Business or Enterprise plans on Collabora's pricing page, where the Business plan is listed at 3 euros per user per month for up to 99 users. Confirm current terms directly with Collabora before you decide, since plan details can change.
What drives the cost of fixing a connection problem?
Cost follows the time needed to isolate the fault and the number of environments involved. One-time costs cover the diagnosis and the fix itself. Recurring costs appear only if you choose ongoing support or a subscription. The main drivers are the number of components in the request path, the availability of logs and access to the proxy and firewall, whether the fault is intermittent, and whether it recurs after a change. Ask any provider to price the diagnosis and the fix separately, to state what is excluded, and to explain how a change in scope would be handled.
Which logs should we check first when documents will not load?
Start with the Nextcloud log for the request that failed, then the Collabora Online server log for the same time window. On the Nextcloud side, check the Office app settings and the WOPI and discovery requests. On the Collabora side, look for rejected WOPI hosts and WebSocket handshake failures. Confirm that the WebSocket upgrade headers survive the reverse proxy, and that the Collabora server URL and protocol match the Nextcloud installation. Confirm exact log locations and log level settings in the official Nextcloud and Collabora documentation for your version, since they differ between packages and containers.
Security considerations while fixing connection errors
Connection errors tempt teams to open access, turn off checks or share raw logs to get documents loading again. The cards below cover the controls that should survive the fix, so that a working connection does not leave the WOPI path weaker than it was.
Restrict WOPI requests by source
Nextcloud's administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers. When you change load balancers, NAT or DNS during troubleshooting, the source addresses can change, so check the allow list again after each change. Do not widen it to a whole subnet to make a test pass. Confirm the addresses Nextcloud actually sees from the Collabora side before you close the ticket.
Match the protocol on both sides
The Nextcloud manual recommends using the same protocol for the Collabora server URL as for the Nextcloud installation, preferably HTTPS. A mismatch between an HTTP URL and an HTTPS site is a common cause of failed loads and mixed content errors. Fix the scheme in the configured URLs and the reverse proxy, rather than adding exceptions for the mixed pair. Record which scheme each component advertises.
Do not disable TLS verification
Turning off certificate checks between Nextcloud and Collabora can make a connection error disappear, but it also removes the server identity check that protects document traffic. Use a certificate that covers the hostname Nextcloud calls, and add the internal certificate authority to the trust store of the system making the request. If a check fails, the hostname, chain or expiry date is the thing to fix.
Keep document content out of shared logs
Connection debugging usually means sharing logs with a vendor, a partner or a ticket queue. Request and error logs can carry file names, paths and sometimes fragments of content, so trim them before sharing. Raise log levels only for the window you need, then return them to normal. Treat debug output as sensitive data with the same handling rules as the documents themselves.
Apply vendor security updates first
Collabora publishes security advisories for Collabora Online. The 25.04 release notes record that 25.04.7.5, released January 29, 2026, fixed CVE-2026-23623 and updated package signing keys for RPM and DEB users. Before tuning configuration to chase an error, confirm the server runs a patched point release for its branch. Verify the new signing keys during package updates so that the fix itself is not installed from an untrusted source.
When to stop troubleshooting and redesign the deployment
Stop patching when the same unexpected connection error returns after each fix, or when it appears only after a network change such as a new firewall rule, a changed DNS record, a moved reverse proxy or a new Nextcloud hostname. Those patterns usually mean the deployment depends on values that were never pinned down: the public URL Nextcloud uses for WOPI, the URL Collabora advertises in its discovery, the address range that the WOPI allow list permits, and whether both sides agree on HTTPS. If you have corrected each of these once and the failure still comes back, the problem is in the design, not in a single setting.
Redesign is also the right call when the topology has outgrown one server. Collabora's Helm chart documentation states that load balancers must route by the WOPISrc parameter so every user editing one document reaches the same pod, and that horizontal pod autoscaling is disabled because scaling breaks collaborative editing. If you run several Collabora servers behind a proxy that balances by connection instead of by WOPISrc, users will see intermittent failures that look like connection errors but are really documents being split across servers. Confirm the routing method before adding a second server, and treat its absence as a reason to redesign the ingress layer first.
The decision between fixing and redesigning comes down to whether you can name the one thing that changed and reverse it. If you can, fix the existing setup and record the change. If you cannot, plan a redesign that fixes the hostname, the proxy configuration, the allow list and the TLS termination together, and rehearse it in a non-production Nextcloud instance first. Ask your team and any partner to confirm the scope, dependencies and rollback steps in writing before work begins, since the effort depends on how many integrations and users share the same Collabora endpoint.
How DeployOpen scopes and delivers connection fixes
DeployOpen works on Collabora Online connection errors in Nextcloud as a bounded piece of work inside your own infrastructure. We start from the failing request, trace it across Nextcloud, the reverse proxy and the Collabora server, and deliver a fix with logs, configuration and a written record of what changed.
How we scope
- Engagements are fixed-scope, with the systems covered and deliverables agreed in writing before work starts.
- The written scope lists the Nextcloud version, Collabora Online version, proxy type and network paths in use.
- Ongoing support and continuous testing are available as a retainer if you want cover after the fix.
How we build
- We collect capability and discovery output from Nextcloud and check the Collabora server URL and protocol.
- We review reverse proxy configuration for WebSocket upgrade rules and confirm requests reach the correct backend.
- We test document opening from several user accounts and browsers, then compare Nextcloud and Collabora logs for the same request.
How we hand over
- You receive the corrected configuration files, with each change explained and tied to the symptom it resolved.
- You receive a short runbook covering the checks used, the log locations and the order to rerun them.
- We document the verification steps so your team can repeat the test after future upgrades or network changes.
How we support
- Ask your team to record the exact error text, time of failure and affected user before contacting us.
- Confirm with your Nextcloud and Collabora release notes whether a known issue applies to your versions.
- Agree in the written scope who owns changes after handover, and whether a retainer covers future regressions.
