Fix Collabora Online “Socket Connection Closed Unexpectedly”: WebSocket and Proxy Checks

Collabora Online can look healthy at first glance and still fail as soon as the editor tries to establish its live WebSocket. The familiar symptom is a document that begins loading and then reports that the socket connection closed unexpectedly, sometimes accompanied by a failed wss:// request in the browser. In 2026 there is one version-specific reason to check before changing anything else: the 26.04 branch introduced a more compact WebSocket URL, and older reverse-proxy rules can conflict with it.

Collabora's official CODE 26.04 release notes say that CODE 26.04.1, released June 8, 2026, required Apache2 reverse-proxy users to change their ProxyPass rule for the new compact WebSocket URL. The later 26.04.2.x notes say that CODE can fall back to the legacy URL when the new route cannot be used and emits an audit warning that points administrators back to the current proxy recommendations. The enterprise Collabora Online 26.04 branch is also current in 2026, so administrators should compare any proxy configuration copied from an older 24.04 or 25.04 guide with the latest vendor documentation before treating the problem as a random network fault.

What the error actually means

The message does not identify a single root cause. It means the browser-to-Collabora WebSocket either never upgraded successfully or was established and then terminated unexpectedly. That distinction matters because the fixes differ.

1. Check whether the failure started after a 26.04 upgrade

Als het probleem zich direct voordoet na de overstap van versie 25.04 of een oudere CODE-image naar 26.04, beschouw de reverse proxy dan als de eerste verdachte. Dit is geen speculatie: Collabora heeft de wijziging van de compacte WebSocket-URL gedocumenteerd in de release-opmerkingen van versie 26.04, en een officieel projectprobleem meldde dat WebSockets niet meer werkten na een upgrade naar 26.04.1 totdat de Apache-proxyregels waren aangepast.

Los dit niet op door blindelings terug te gaan naar een eerdere versie en de oude proxy ongewijzigd te laten. Een rollback kan een tijdelijke oplossing zijn, maar de definitieve oplossing is om de proxy af te stemmen op de versie die u wilt gebruiken. Gebruik voor Apache de huidige Collabora Online proxy-instellingen in plaats van een versie van vóór 26.04. In het eigen rapport van Collabora over WebSocket in versie 26.04 wordt een geval beschreven waarin het bijwerken van de Apache-regels de werking herstelde.

2. Bewijs of HTTP werkt terwijl WebSocket faalt.

Test eerst de standaard Collabora-eindpunten:

curl -I https://office.example.com/hosting/discovery
curl -I https://office.example.com/hosting/capabilities

Een succesvolle reactie bewijst dat DNS, TLS, de front-endproxy en ten minste een deel van de Collabora-service bereikbaar zijn. Het bewijst echter niet dat het bewerken van documenten zal werken. De editor is afhankelijk van een WebSocket-route onder /cool/, die andere proxyvereisten heeft.

Open vervolgens de ontwikkelaarstools van de browser, reproduceer de fout en inspecteer het netwerkpaneel met het WS-filter. Een succesvolle WebSocket-handshake zorgt normaal gesproken voor een upgrade van de HTTP-verbinding; RFC 6455 definieert de serverrespons als HTTP-status 101 wanneer de upgrade slaagt. Als u in plaats daarvan 400, 404, 405, 502 ziet of een direct mislukte aanvraag, vergelijk dan de tijdstempel met de logbestanden van de reverse-proxy en coolwsd.

3. Corrigeer het Nginx WebSocket-pad en de headers.

Voor Nginx zijn de belangrijkste eigenschappen eenvoudig: het verzoek moet het Collabora- /cool/pad bereiken, de proxy moet HTTP/1.1 gebruiken voor een klassieke WebSocket Upgrade-flow, de Upgradeheaders Connectionmoeten worden doorgestuurd, de oorspronkelijke Host moet behouden blijven en de lees-time-out moet lang genoeg zijn voor een bewerkingssessie.

De Collabora SDK-handleiding toont al lange tijd een speciale WebSocket-locatie met Upgrade, Connection, Host, en een lange proxy_read_timeout. Een officiële documentatie-uitgave van het Collabora-project wees ook op de noodzaak van WebSocket-headers op de bredere /coolroute. Een conservatief, 26.04-compatibel patroon is:

location ^~ /cool/ {
    proxy_pass http://127.0.0.1:9980;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 3600s;
}

Plak dit niet over een werkende productieconfiguratie zonder het upstream-adres, het TLS-model, de padafhandeling en eventuele bestaande beveiligingsmaatregelen aan te passen. De juiste aanpak is om uw topologie te behouden en tegelijkertijd te voldoen aan de huidige route- en headervereisten van Collabora.

Waarom time-outwaarden belangrijk zijn

WebSocket-bewerkingssessies duren lang. De huidige Helm-waarden van het Collabora-project beschrijven dit expliciet en gebruiken een ruime proxy-time-out voor de meegeleverde Nginx-proxy. Als uw edge load balancer, Kubernetes ingress, CDN, firewall of reverse proxy inactieve verbindingen eerder sluit dan de applicatie verwacht, kunnen gebruikers een tijdje normaal bewerken en worden ze vervolgens met een vast interval losgekoppeld.

Als de fout zich telkens na ongeveer hetzelfde aantal seconden voordoet, controleer dan alle tussenliggende schakels in het pad in plaats van alleen de time-out van Nginx te verhogen. De kortste time-out heeft de doorslag.

4. Zorg voor consistente TLS-terminatie

Een veelvoorkomende implementatie beëindigt HTTPS bij Nginx, Apache, HAProxy, Traefik of een ingress controller en stuurt gewoon HTTP door naar Collabora op poort 9980. In dat ontwerp vereist de officiële configuratie van Collabora dat de back-end weet dat TLS door de proxy wordt beëindigd. De SDK-handleiding beschrijft ssl.enable=falsedit ssl.termination=truemodel.

Bij een Docker-implementatie wordt dit doorgaans uitgedrukt via de extra parameters van Collabora:

--o:ssl.enable=false --o:ssl.termination=true

Gebruik deze opties alleen wanneer TLS daadwerkelijk stroomopwaarts wordt beëindigd. Als de proxy in plaats daarvan via HTTPS verbinding maakt met Collabora, configureer die topologie dan consistent in plaats van de twee modellen te combineren. Een mismatch kan leiden tot verkeerde schema's, onjuiste WebSocket-URL's, certificaatfouten of omleidingen die de upgrade verstoren.

5. Controleer op inconsistenties tussen host en origin in de coolwsd-logbestanden.

Collabora valideert WebSocket-origins. Als het logboek woorden bevat zoals Rejecting WebSocket upgradegevolgd door een origin en een verwachte host, corrigeer dan de relatie tussen de externe hostnaam en poort in plaats van willekeurig permissieve headers toe te voegen. De officiële Collabora-probleemtracker bevat een gedocumenteerd voorbeeld waarbij een geconfigureerde servernaam, inclusief , :443niet overeenkwam met de browser-origin zonder die expliciete poort.

Welke commando's nuttig zijn, hangt af van uw installatie:

docker logs collabora --tail 200
journalctl -u coolwsd --since "10 minutes ago"
nginx -t
apachectl configtest

Zoek naar de eerste foutmelding tegelijk met het mislukte WS-verzoek. Berichten over geweigerde upgrades, onjuiste URI-syntaxis, een onverwachte host of een niet-beschikbare upstream-server zijn nuttiger dan de standaard pop-up in de browser.

6. Als alleen browsers op basis van Chromium problemen veroorzaken, controleer dan de afhandeling van HTTP/2 of HTTP/3.

Dit is een minder specifiek geval, maar het is de moeite waard om te controleren voordat de server opnieuw wordt opgebouwd. Het Collabora-project heeft een Chromium-gerelateerd geval gedocumenteerd waarbij een proxy een HTTP/2 CONNECT WebSocket-verzoek rechtstreeks naar coolwsd doorstuurde en een 405 Method Not Allowed-foutmelding ontving. Een ander probleem beschrijft fouten bij het laden van documenten met HTTP/3/QUIC in een specifiek proxypad. Deze meldingen betekenen niet dat HTTP/2 of HTTP/3 altijd moet worden uitgeschakeld; ze betekenen dat de tussenliggende partij het clientgedrag moet vertalen naar een WebSocket-verbinding die Collabora ondersteunt.

Als Firefox wel werkt maar Chrome niet met hetzelfde account en document, leg dan het protocol en de statuscode van de proxy vast. Het is beter om het gedrag van de proxy/inkomende verbinding te corrigeren dan om moderne protocollen globaal uit te schakelen, tenzij er in uw omgeving geen compatibel alternatief is.

7. Start pas opnieuw op nadat de configuratie is gevalideerd.

Test eerst de syntaxis van de proxy. Herlaad vervolgens de applicatie in plaats van herhaaldelijk blindelings opnieuw op te starten:

sudo nginx -t && sudo systemctl reload nginx
sudo apachectl configtest && sudo systemctl reload apache2

Voor containers geldt dat u de Collabora-service alleen opnieuw moet starten als u de omgeving of instellingen ervan hebt gewijzigd coolwsd. Een wijziging die alleen de proxy betreft, vereist normaal gesproken alleen het opnieuw laden van de proxy.

Hoe u zelf kunt controleren of het probleem is opgelost

Gebruik een korte verificatiereeks in plaats van te vertrouwen op één enkele succesvolle documentopening:

• Bevestig /hosting/discoverydat ze /hosting/capabilitiesbereikbaar zijn via dezelfde openbare hostnaam die gebruikers gebruiken.
• Open een document en controleer of de WS-aanvraag van de browser succesvol wordt uitgevoerd en geen 4xx/5xx-foutmelding geeft.
• Voer meerdere bewerkingen uit, wacht langer dan de oude foutinterval en controleer of de verbinding stabiel blijft.
• Sla het document op en sluit het, open het vervolgens opnieuw om te controleren of de WOPI-rondreis in orde is.
• Controleer de coolwsd- en proxylogs op geweigerde WebSocket-upgrades, fouten bij het parseren van URI's of herhaalde herverbindingslussen.
• Als uw implementatie een load balancer of ingress heeft, herhaal dan de test via de daadwerkelijke productieroute in plaats van rechtstreeks verbinding te maken met poort 9980.

Welke oplossing moet je kiezen?

Als u hebt geüpgraded naar versie 26.04 en Apache gebruikt, is het bijwerken van de proxyregels de actie met de hoogste prioriteit, omdat Collabora deze wijziging expliciet heeft gedocumenteerd. Als de verbinding na een vaste periode wordt verbroken, concentreer u dan op de time-outinstellingen voor elke netwerkhop. Als de fout zich direct voordoet in alle browsers, controleer dan /cool/de routering, de upgradeheaders, de consistentie van host/origin en de TLS-terminatie. Als slechts één browserfamilie problemen ondervindt, vergelijk dan de afhandeling van het HTTP-protocol voordat u Collabora zelf aanpast.

De sleutel is om te voorkomen dat "socketverbinding onverwacht verbroken" standaard wordt behandeld als een crash van de Collabora-applicatie. In veel implementaties functioneren de editor, het discovery-eindpunt en de WOPI-host naar behoren, terwijl de reverse proxy de verbinding die het meest van belang is voor live bewerken, namelijk de langdurige WebSocket, niet goed afhandelt.

Officiële referenties

• Release-opmerkingen voor Collabora CODE 26.04
• Release-opmerkingen voor Collabora Online 26.04
• Collabora Online SDK proxy-instellingen
• CollaboraOnline/online probleem #15918: WebSocket-fout na upgrade naar 26.04
• CollaboraOnline/online issue #13751: WebSocket-headers in proxy-documentatie
• Standaardwaarden voor de time-out van de Collabora Online Helm-proxy
• RFC 6455: Het WebSocket-protocol