Why Collabora refuses WOPI requests after a network change
Collabora refuses a WOPI request when the WOPI host and the Collabora server do not both accept each other's address and protocol. Both sides must match after a change, so a fix that only touches one side will leave documents failing to open. Teams usually reach this page when editing stops working after a move to a new hosting location, a new reverse proxy, a NAT or firewall change, or a DNS update, and Nextcloud shows an unauthorized host or allow list warning. The same symptom can also appear when the Nextcloud server URL or the Collabora server URL changes protocol, for example from HTTP to HTTPS.
The Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers, and using the same protocol for the Collabora server URL as for the Nextcloud installation, preferably HTTPS. After a network change, the addresses Nextcloud sees for Collabora may no longer be the ones Collabora uses to call back, because a proxy, NAT rule or load balancer can rewrite the source. Confirm which addresses each side sees before you edit any list, and confirm with your network team whether traffic passes through a translation layer on the way.
By the end of this page you should be able to check four things: the Collabora server URL and protocol configured in Nextcloud, the address ranges Collabora presents to Nextcloud, the allow list entries on the Collabora side, and whether requests succeed in each direction. Each check can be run from the Nextcloud host and from the Collabora host, which shows which side is refusing the request. Keep a record of the old and new addresses and the time of the change, because that record makes it much faster to tell a stale allow list entry from a broken route.
Which error points to which side
Nextcloud acts as the WOPI host. Collabora calls back to Nextcloud to fetch and save documents, so Nextcloud can refuse those callbacks when the caller does not match its WOPI restrictions. The typical symptom is that the editor starts, then fails to load the file or fails on save, while Nextcloud's own log records the refused request. Check the Nextcloud log first, in the data directory unless your installation writes it elsewhere.
- Caller not on the WOPI allow list: Nextcloud can restrict WOPI requests to specific IP addresses. If Collabora's outbound address changed, that address no longer matches.
- Protocol mismatch: the Collabora server URL and the Nextcloud URL should use the same protocol, preferably HTTPS. A mismatch can look like a refused request.
- Wrong public URL: if Nextcloud generates links with an internal hostname, Collabora may call an address Nextcloud does not expect.
- Changed server identity after a migration: new hostnames or certificates often change both the URL and the allowed address at the same time.
Confirm the expected Collabora address and protocol against the Nextcloud Office configuration guide before editing anything on this side.
Collabora Online checks the WOPI host that is named in each request before it loads a document. Its allow list and aliasgroups decide which hosts it accepts. A refusal here means Collabora received the request but did not accept the host it came from or the host name it was given. Users usually see the document fail to open, and the Collabora server log, not Nextcloud's, holds the explanation.
- Allow list rejects the WOPI host address: the address Collabora sees for Nextcloud is not in its configured allow list, which is common after a server move or a change to outbound NAT.
- Aliasgroup does not match the host name: the host name in the WOPISrc parameter must match an entry in the aliasgroup configuration. A renamed Nextcloud domain is a frequent cause.
- Name resolves to a different address: DNS changes can make the name point somewhere Collabora does not expect, even when the configuration text is correct.
- Changed configuration not reloaded: confirm that the running service picked up the new settings, since a restart may be required.
Find the logs with your service manager or container runtime, and check the exact refusal text with your Collabora version. Test the path from the Collabora host with a request to the Nextcloud WOPI endpoint to see which address and host name Collabora actually sends.
A reverse proxy or load balancer between Nextcloud and Collabora can change the information each side relies on. It may set the client address to its own address, rewrite the Host header, or terminate TLS and change the scheme. Either side may then refuse a request that looks correct at its origin. These failures often appear only from some networks or after a proxy change, because the rewritten values depend on the route taken.
- Forwarded client address is wrong or missing: if the proxy does not pass the original address, the receiving side sees the proxy address and compares it with the wrong entry.
- Host header rewritten: a changed Host value can break the name match on the Collabora side and the URL checks in Nextcloud.
- Trusted proxy settings missing: Nextcloud only trusts forwarded headers from proxies it is configured to trust. Check the trusted proxy setting for your installation.
- Scheme changed at TLS termination: a request that arrives as plain HTTP internally can trigger protocol checks that expect HTTPS.
Compare the headers each side receives with the headers the proxy sent. Use the proxy access and error logs, and confirm the routing and header rules with your proxy vendor's documentation for your version before changing them.
How to match allow lists and aliasgroups after a change
This sequence brings the Collabora Online WOPI allow list and aliasgroup entries back in line with the addresses Nextcloud and the proxy chain now use. Each step ends with a check, so the result is a document that opens from Nextcloud and a record of which host names and addresses Collabora accepts.
Record current addresses and the proxy chain
The Nextcloud operator and the network or platform engineer list every name and address involved: the public Collabora hostname, the Nextcloud hostname, the address each side sees for the other, and each reverse proxy, load balancer, NAT or CDN hop between them. Note which side sets the forwarded headers at each hop. Done means you have a written table with one row per hop, and every row names the source address Collabora will see when Nextcloud calls it.
Confirm protocol and URL in Office settings
The Nextcloud administrator opens the Nextcloud Office settings and checks the Collabora server URL against the table from the previous step. The Nextcloud administration manual recommends using the same protocol for the Collabora server URL as for Nextcloud, preferably HTTPS. Done means the URL in settings uses the intended scheme, host and port, and matches the public name Collabora presents.
Update allow list and aliasgroup entries
The Collabora administrator edits the WOPI host configuration in the
storage.wopisection ofcoolwsd.xml, adding the host names and addresses from the table, including any internal route that Nextcloud uses. Confirm the exact key names for your installed version before editing. Keep entries as narrow as the environment allows, and remove old addresses that no longer exist. Done means the file diff lists only the expected entries and a peer reviewer has checked it.Reload the services that read the change
The operator restarts or reloads the coolwsd service so it reads the updated configuration, and reloads any reverse proxy whose routes or forwarded headers changed. Use the reload method your installation documents for each component. Done means both services report running, and the coolwsd startup log shows no configuration parse errors or warnings about the WOPI host entries.
Read the discovery document from Nextcloud
From the Nextcloud host, the administrator requests the Collabora discovery document through the public Collabora URL, for example with curl from the same network path Nextcloud uses. Check that the WOPI endpoints in the response use the scheme and host name confirmed in step two. Done means the discovery response is returned over the expected protocol, and the advertised URLs match the Collabora URL in Nextcloud settings.
Verify Collabora accepts the WOPI host
Open a test document from Nextcloud with a user who belongs to an allowed group, then check the coolwsd log for unauthorized host or allow list messages. Repeat the test from a host outside the new entries to confirm it is refused. Done means the test document opens, the log shows no rejection for the expected host, and the outside host is refused as designed. Record the result with the date and the configuration version.
Allow list options and when each fits
This table compares the three ways to restrict WOPI requests: fixed IP addresses, host names through aliasgroups, and a single reverse proxy address. Read each row against your own network to see where maintenance effort lands and which option fits your addressing model. The main takeaway is that the option with the least churn after a network change is the one tied to addresses you control and rarely reassign.
| Option | Maintenance after network changes | Risk during DNS or NAT updates | When it fits |
|---|---|---|---|
| Fixed IP addresses of Collabora servers | Every new, replaced or re-addressed Collabora node needs an allow list update on the Nextcloud side | Low if addresses are static, but a NAT rule change can present a different outbound address than expected | Stable on-premises addressing where Collabora servers keep the same IPs for long periods |
| Host name matching through aliasgroups | Updates follow DNS or host naming changes rather than each server address, but names must still be kept in sync | Medium: a stale or mis-resolving name can cause refusals even when the server is healthy | Environments where Collabora is reached by a consistent name and addresses change more often than names |
| Single reverse proxy address | Only the proxy address changes need updating, so the list stays short | Medium: if traffic reaches Nextcloud through a different hop than the proxy, the request source may not match | Setups with one ingress point in front of Collabora, where the proxy address is fixed and known |
| Dynamic cloud addressing | Fixed IP lists need frequent review, so host name or proxy-based matching usually needs less upkeep | High for raw IP lists when instances are replaced or egress addresses change | Cloud deployments with autoscaling or changing addresses, where name-based matching or a stable proxy is easier to keep correct |
| Confirmation required | Confirm the exact allow list and aliasgroup keys for your Collabora version before changing anything | Test each change from both the Nextcloud and Collabora sides after DNS or NAT edits | Follow the Nextcloud administration manual's recommendation to restrict WOPI requests to Collabora server IPs, and check your version's configuration keys |
Security trade-offs of loosening or tightening allow lists
Every change to a WOPI allow list trades convenience against exposure. The cards below cover the risks that tend to appear when teams widen a list to clear an error, leave old entries behind, or trust headers that a client can set. Review each change against these risks before it goes live.
Over-broad allow lists
A list that covers a whole subnet or a broad address range lets hosts you never intended call WOPI endpoints on Collabora Online. Start from the exact addresses of your Nextcloud servers and the Collabora servers, then widen only when a documented address is missing. Check that each entry is a single host or a tight range, and confirm with your network team which hosts actually sit in that range.
Stale entries after decommissioning
When a Nextcloud node, load balancer or Collabora server is retired, its address often stays on the allow list. A reused address can then belong to a different machine that is still trusted. Review the list on a set schedule and remove entries tied to hosts that no longer exist, and confirm each remaining address still maps to a live service you own.
Trusting spoofable forwarded headers
If Collabora decides which client is calling based on X-Forwarded-For or similar headers, any client that can reach the service can set those headers to a trusted address. Only trust forwarded headers from the reverse proxy you control, and make sure the proxy overwrites client-supplied values. Test by sending a request with a forged header from an untrusted network and confirming it is refused.
Mismatched HTTP and HTTPS URLs
Allowing a host over plain HTTP while the Nextcloud installation runs on HTTPS can expose document traffic and tokens to interception. The Nextcloud administration manual recommends using the same protocol for the Collabora server URL as for the Nextcloud installation, preferably HTTPS. Check the configured URL on both sides and reject any setting that downgrades the scheme.
Change control for allow list edits
Allow list changes alter who can reach your document editing path, so each one should have a change ticket. Record the requester, the exact entries added or removed, the reason, the test results from both sides, and the rollback step. Tickets also give auditors and later operators a trail for why an address was trusted.
Hardening guidance covered separately
Allow lists are one layer of control. Proof keys, access tokens and TLS settings change the security posture as much as the list does, and they are covered in the Collabora Online security hardening guidance. Review those controls alongside any allow list change so that a widened list does not weaken the overall setup.
Questions operators ask before fixing WOPI errors
How long does a typical WOPI allow list fix take?
No supplied figure gives a standard duration for this fix, so treat any number you hear as a guess until it is scoped against your environment. The main drivers are the number of Nextcloud and Collabora hosts involved, whether your change control process requires a window and approvals for each allow list edit, and how quickly your team can get access to both admin consoles and the reverse proxy. A single Nextcloud server pointing at one Collabora server with a stable address is a small job. Several Collabora nodes behind a load balancer, plus a network team that controls the proxy, takes longer. Ask any provider to break the estimate into discovery, change work, testing from each side and documentation, and to state which of those depends on your change calendar.
Can our internal team fix WOPI allow list errors without outside help?
Yes, if the team has someone who can read Nextcloud and Collabora logs, change the Nextcloud Office settings, and edit the proxy or firewall rules that carry WOPI traffic. The Nextcloud administration manual describes restricting WOPI requests to the IP addresses of the Collabora servers and using the same protocol for the Collabora server URL as for Nextcloud, so the core steps are documented. Outside help tends to add value when the path between the two servers crosses several network layers, when the Collabora servers sit behind a load balancer whose outbound addresses are not obvious, or when the team needs a repeatable test set and written evidence for an assessment. Decide based on who has the knowledge and the access, not on the error message alone.
What access and materials does the work need from us?
Plan to provide the following before work starts:
- Administrator access to Nextcloud, including the Nextcloud Office settings, and to the Collabora Online configuration for each server involved.
- Administrator access to the reverse proxy, load balancer, and firewall or cloud security group rules that sit between the two servers.
- Read access to Nextcloud logs and to Collabora Online logs on every node, with the time zone and log levels agreed in advance.
- A set of test documents in docx, xlsx and pptx, plus an ODF file, so you can confirm that opening, editing and saving work from each side.
- Named contacts who can approve a change window and roll back a change if a test fails.
Ask the provider to confirm exactly which of these they need in writing so that access requests do not stall the job.
What does a fixed-scope DeployOpen engagement cover for WOPI errors?
A fixed-scope engagement is agreed in writing before work starts, so scope, deliverables and timelines are visible to you before any change is made. For this topic, a reasonable written scope would list the hosts and addresses in use, the WOPI host allow list settings to review on each side, the proxy and firewall rules to confirm, the test cases run from Nextcloud and from Collabora, the change steps and rollback plan, and the documentation handed over. DeployOpen plans, implements, hardens and documents self-hosted open-source platforms in your own infrastructure, so the changes are made in your environment. DeployOpen does not issue audit reports or certifications, so if you need evidence for an assessment, the engagement prepares that evidence for your independent auditor. Ask for the scope list and deliverables to be named in the quote.
Do we need to rerun the WOPI test after every network change?
Yes, rerun the test after any change that can alter the source address Collabora uses to reach Nextcloud, or the address Nextcloud uses to reach Collabora. That includes moving a server, changing NAT or egress rules, adding a load balancer or node, changing a DNS record that the allow list depends on, and updating the reverse proxy. The Nextcloud guidance on restricting WOPI requests to Collabora server addresses means a silent address change can produce refusals that look like unrelated editing failures. A short, repeatable test set covering opening, editing and saving from each side is enough to catch most of these problems. Record the result and the change reference each time so that the next person can see what changed and when.
What does it cost to fix WOPI allow list errors?
The cost comes from the labor to investigate, change and test the configuration, plus any change-control work your organization requires. The one-time part is the initial diagnosis, the allow list and proxy changes, and the test and documentation work. The recurring part is the retest after each network change and the maintenance of the allow list as addresses change. No supplied figure gives a price for this work, and DeployOpen does not publish a price list, so a quote follows from the written scope. Ask for the quote to separate discovery, change work, testing, documentation and any retainer for ongoing retesting. If you run Collabora Online on a subscription, the Collabora pricing page lists the Business plan at 3 euros per user per month for up to 99 users, but that is a licensing cost and does not cover this configuration work.
How do we check that the allow list works from both sides?
Test from Nextcloud first by opening a document, then test from the Collabora side by confirming that the WOPI host requests from Nextcloud arrive and succeed in the Collabora logs. Use the same protocol for both URLs, preferably HTTPS, as the Nextcloud administration manual recommends. Look for WOPI host refusals or unauthorized responses in the Collabora Online logs, and check the source address shown there against the entries in your allow list. Repeat with a test document in each format you support, and confirm that saving works, not only opening. Keep a short written record of the source addresses, the settings you changed and the test results, so the next network change can be checked against a known baseline.
Testing WOPI access from the Nextcloud side and the Collabora side
Test each side on its own before you test the whole chain. A WOPI failure can sit in either system, and a single end-to-end attempt only tells you that something is wrong. Start on the Nextcloud side. From the Nextcloud server itself, not from your laptop, request the Collabora discovery URL and confirm it answers over the protocol you configured. The response should list the file types and actions the server supports. If the request fails here, the problem is network reachability, DNS, TLS or a reverse proxy rule, and no change to the allow list will help. Also confirm that the Collabora server URL in Nextcloud uses the same protocol as the Nextcloud installation, since the Nextcloud administration manual recommends matching them, preferably on HTTPS.
Next, test the Collabora side. Confirm that a WOPI host request arriving from the Nextcloud server's address is accepted, which means your allow list must include the address Collabora actually sees. Behind a load balancer, NAT gateway or proxy, that address is often not the one you expect, so check the source address in the Collabora logs during a test request rather than trusting the configuration file. Then open a sample document end to end from Nextcloud, using a non-sensitive file in a test account. Use a document type that exercises the editor, such as a short .docx and a .xlsx, so you can see whether the failure depends on the file type.
Do not conclude that a fix worked until both systems' logs agree. Protocol mismatches and allow list rejections often show up as a successful page load on one side and a refused request on the other, so a document that opens once proves little. Compare the timestamps of your test request in the Nextcloud log and the Collabora log, confirm the same protocol and host name appear in both, and repeat the sample open after any restart or proxy change. Record which address and protocol each test used, so the next change can be checked against the same baseline. Your security team should also confirm that the test documents contained no production data and that the logs you reviewed were handled under your normal retention rules.
How DeployOpen scopes and resolves WOPI access issues
This sequence turns an unexplained WOPI refusal into a documented, tested allow list that matches the current network path, agreed in writing before any change is made.
Review the current network path with your team
DeployOpen works with your network, platform and security teams to map the request path between the Nextcloud server, any reverse proxies or load balancers, and the Collabora Online servers. We record which addresses each hop presents, whether NAT or a proxy rewrites the source, which protocol and hostname are used for the Collabora server URL, and where the allow list is configured on each side. The output is a reviewed diagram and a list of the configuration keys in use, confirmed by your team before we move on.
Collect logs and configuration from both sides
We gather the relevant entries from the Nextcloud and Collabora Online logs for the refused requests, together with the active WOPI host settings and aliasgroup configuration. Where possible we compare the source address recorded in each log with the address the network path actually shows, so mismatches between what Collabora sees and what Nextcloud expects are visible before any change. The step is complete when each refusal can be traced to a specific request, source address and configuration entry.
Agree a written fixed scope
Based on the findings, DeployOpen writes down the scope: the systems covered, the allow list entries to be added, removed or corrected, the test cases on each side, and the handover documents. Most engagements are fixed-scope, so the scope, deliverables and timelines are agreed in writing before work starts. DeployOpen does not publish a price list, and a quote follows from the written scope. Ask for the quote to list the components separately so you can see which parts are one-time and which would recur, such as later retesting after network changes.
Make changes under your change process
All configuration changes are made through your change management process, in the maintenance windows and with the approvals your organization requires. DeployOpen prepares the proposed changes as exact configuration diffs for the Nextcloud and Collabora Online settings, and keeps a rollback copy of the previous values. The step is done when each change has an approved change record that references the scope item it implements.
Test from the Nextcloud side and the Collabora side
We test each path in both directions. From the Nextcloud server, we confirm that the Collabora Online discovery and WOPI requests are sent from the expected source and are accepted. From the Collabora side, we confirm that requests from the Nextcloud host are allowed and that requests from an address outside the list are refused. We also check that a document opens, saves and reopens for a test user with the protocol and hostname in use. The step closes when every test case in the scope has a recorded pass with its log evidence.
Hand over documented allow list entries
DeployOpen delivers a handover document listing each allow list entry, the address or range it covers, the reason it exists, the setting that holds it on each side, and the test that proves it. The document also states what to recheck after network changes such as new proxies, NAT updates or IP address reassignments. Your team confirms receipt and the scope is closed when the handover is accepted in writing.
