Skip to Content

Published

Correct the Installation Troubleshooting tree

Last modified by Eleni Cojocariu on 2026/08/19 15:42

Review of the Installation Troubleshooting topic and its children against the Documentation Guide, checking the pages against the platform sources and against the legacy page they came from (Documentation.AdminGuide.Installation at version 157.1, the last revision before the migration).

Three of the findings make a reader worse off than the error they arrived with.

Wrong solutions

  • Multiple Instances of XWiki in the Same Container told the reader to add <jmx duplicate-domains="true"/> to the Infinispan configuration. That attribute was removed in Infinispan 10: the shipped WEB-INF/cache/infinispan/config.xml declares urn:infinispan:config:15.2 in 17.10.4 and in 18.7 alike, and the 15.2 schema's jmx element accepts only domain, enabled and mbean-server-lookup. An unknown attribute in a schema-validated configuration stops the cache container from starting. The file also already contains a jmx element, so "add the element" was wrong in shape too. The Solution now edits its domain attribute, which is what makes the domains unique.
  • SSL Certificate Error blamed "versions of Java 8 older than update 101" and prescribed upgrading Java 8 to update 101. Java 8 has not been supported since XWiki 14.0, and XWiki 18 requires Java 21 or 25; the pasted stack trace was from 2017 and framed on sun.security.ssl.Alerts, removed in JDK 11. The page now explains the truststore, names the two situations that actually produce a PKIX failure (a TLS-inspecting proxy, a self-signed internal certificate) and solves it with keytool.
  • "File Path too Long" on Windows when Unzipping named the registry value EnableLongPaths. The value Windows reads is LongPathsEnabled, so the documented fix did nothing. Its MSDN link also 301s to a page where the #maxpath anchor no longer exists, and now points at the current Microsoft page.

The legacy page dead-ended readers

Documentation.AdminGuide.Installation still contained See [[]]. under both "Getting an error about SSL certificate" and ""File path too long" on Windows when unzipping", rendering as See Installation. with href="#". Both now point at the new pages. Its "Unsupported major.minor version 51.0" section still described Java 6 and 7 and had the offline-installation link stranded underneath it; the section is repointed at XWiki Startup Failure after a Required Java Upgrade, which documents that symptom on a supported version, and the offline link gets its own heading back.

The proxy pages

XWiki behind a Proxy Server carried two full configuration procedures inside its Solution section, nested in bullets, plus a "Tomcat 8+" that no supported XWiki runs on (a Servlet 5.0 container is required, and the distribution builds packages for Tomcat 10 and 11 only) and a Windows example that had lost the https proxy properties the Linux one had. Those steps are now a How-to of their own, Configure XWiki to Use a Proxy Server, leaving the Explanation with the symptom, the cause and the route to the fix. The Java 6 networking-and-proxies link and the "alteratives" typo are gone.

Debug Proxy Configuration ended on "Save the Page and notice the information on the Page", with no result step, no screenshot, and it had dropped the legacy page's one piece of guidance about *what* to look at. Its connectivity test also called httpbin.org, which was returning 503 and 504 while this was reviewed. It now verifies the thing the reader actually cares about, an extension search, in four steps with three screenshots captured on a local 18.4.3 instance. The legacy Groovy dump is kept as a FAQ entry, since reading the values from inside XWiki is still the only way to see what the runtime resolved rather than what the startup script passed; the entry says it takes programming rights, which a wiki administrator does not hold by default on a stock instance.

Its page name was debug, which says nothing from a search result. It was renamed to debug-configuration before this Change Request, with "Update links" and an automatic redirect: that repointed its two backlinks, including the FAQ xobject of the proxy page.

Smaller corrections

  • The hub was titled "Installation Troubleshootings"; every sibling hub uses "… Troubleshooting".
  • The hub's fourth bullet rendered a stray >> inside the link label, from a ~>~> in the source.
  • The hub routed only to its own four children. Its Related field now reaches the other installation-time troubleshooting hubs: Tomcat, Docker, Jetty form content, and Upgrade.
  • The hub had lost the legacy qualifier that the Admin Tools application checks a Tomcat and MySQL installation.
  • Each leaf's Related field listed all three siblings, which the parent's automatic More table already does. They now hold the pages that are genuinely related: Tomcat Troubleshooting from the Infinispan page, the proxy page from the SSL page, the standalone distribution from the unzipping page.
  • <jmx …/> and <cache-container> were written as bare prose and rendered as plain text; they are in code macros now.
  • The title "XWiki behind a Proxy Server" is now "XWiki Behind a Proxy Server", as on "Configure XWiki in Docker Behind a Reverse Proxy".

One deliberate deviation

Configure XWiki to Use a Proxy Server has no screenshot, including on its result step. Every one of its steps edits a startup script or reads a process command line, so there is no interface to capture; the result step shows the produced output instead, the way a Developer page does. Happy to add something if a reviewer would rather see it.

Two titles were left alone on purpose: the quoted error text in ""File Path too Long" on Windows when Unzipping" is kept verbatim, and five pages of the Exports tree link to it with that wording.

All changes

Creation of Configure XWiki to Use a Proxy Server

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Configure XWiki to Use a Proxy Server
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,23 @@
1 +This procedure adds the proxy properties XWiki needs to the process that runs it; [[XWiki Behind a Proxy Server>>doc:documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.WebHome]] describes what fails without them.
2 +
3 +1. Open the startup file in which your installation sets the Java options:(((
4 +|=Installation|=File|=Variable
5 +|On a [[servlet container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]] such as Tomcat|##bin/setenv.sh## on Linux or ##bin/setenv.bat## on Windows, in the container's directory|##CATALINA_OPTS##
6 +|As a [[standalone (demo) distribution>>doc:documentation.xs.admin.installation.methods.install-standalone-demo-distribution.WebHome]]|##start_xwiki.sh## on Linux or ##start_xwiki.bat## on Windows|##XWIKI_OPTS##
7 +)))
8 +1. Add the four proxy properties to that variable, with the host name and the port of your own proxy server:(((
9 +{{code language="bash"}}
10 +CATALINA_OPTS="$CATALINA_OPTS -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777"
11 +{{/code}}
12 +On Windows the same line reads:
13 +{{code language="bat"}}
14 +set CATALINA_OPTS=%CATALINA_OPTS% -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777
15 +{{/code}}
16 +)))
17 +1. Add ##-Dhttp.nonProxyHosts## to the same variable when some hosts must be reached directly, with the exceptions separated by vertical bars.
18 +1. Restart XWiki, and confirm that the properties reached its Java process, whose command line now carries them:(((
19 +{{code language="none"}}
20 +$ ps -ww -C java -o args=
21 +java ... -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777 ...
22 +{{/code}}
23 +)))
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Do the proxy properties belong in ##xwiki.properties##? ==
2 +
3 +No. The Java runtime reads them, not XWiki, so they belong on the command line of the process that runs XWiki.
4 +
5 +== What if the proxy server requires authentication? ==
6 +
7 +Add ##-Dhttps.proxyUser## and ##-Dhttps.proxyPassword## to the same variable, and their ##http## equivalents when the proxy also handles plain HTTP.
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Configure a Servlet Container>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -Installation Troubleshootings
1 +Installation Troubleshooting
Content
... ... @@ -1,8 +1,8 @@
1 -When [[installing>>documentation.xs.admin.installation.WebHome]] or running XWiki, you may encounter some common issues related to configuration, networking, or the runtime environment. For example:
1 +When [[installing>>doc:documentation.xs.admin.installation.WebHome]] or starting XWiki, most of what goes wrong is not in XWiki itself but in the environment it runs in: the servlet container, the network, or the Java runtime. This topic covers the symptoms that appear whatever installation method was used:
2 2  
3 -* errors that occur when deploying [[more than one XWiki instance in the same application server>>documentation.xs.admin.installation.troubleshooting.multiple-instances-container.WebHome]] (for example cache or JMX conflicts).
4 -* ##connection refused## exceptions in the log files if you are [[running XWiki behind a proxy server>>documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.WebHome]]
5 -* [[SSL certificate errors>>documentation.xs.admin.installation.troubleshooting.ssl-certificate-error.WebHome]].
6 -* [["File path too long" on Windows when unzipping~>~>>>documentation.xs.admin.installation.troubleshooting.file-path-long-windows-unzipping.WebHome]].
3 +* a JMX domain conflict that stops the cache from starting, when [[several instances share one servlet container>>doc:documentation.xs.admin.installation.troubleshooting.multiple-instances-container.WebHome]].
4 +* ##connection refused## exceptions in the log files, when [[XWiki sits behind a proxy server>>doc:documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.WebHome]] and cannot reach the extension repositories.
5 +* a PKIX handshake failure when XWiki calls an HTTPS service, described in [[SSL Certificate Error>>doc:documentation.xs.admin.installation.troubleshooting.ssl-certificate-error.WebHome]].
6 +* a [["File path too long" error on Windows>>doc:documentation.xs.admin.installation.troubleshooting.file-path-long-windows-unzipping.WebHome]] while unzipping the distribution.
7 7  
8 -You can check basic XWiki settings using the [[Admin Tools application>>extensions:Extension.Admin Tools Application]]. Note that some features are only supported on Linux.
8 +The [[Admin Tools application>>extensions:Extension.Admin Tools Application]] checks the basic settings of a Tomcat and MySQL installation. Some of its tools only work on Linux.
DocApp.Code.DocumentationClass[0]
Related
... ... @@ -1,0 +1,4 @@
1 +* [[Tomcat Troubleshooting>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.troubleshooting.WebHome]].
2 +* [[XWiki Docker Troubleshooting>>doc:documentation.xs.admin.installation.methods.install-xwiki-docker.troubleshooting.WebHome]].
3 +* [[Unable to Parse Form Content in Jetty>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-jetty.unable-parse-form-content-jetty.WebHome]].
4 +* [[Upgrade Troubleshooting>>doc:documentation.xs.admin.upgrade.troubleshooting.WebHome]].

Summary

Details

Page properties
Content
... ... @@ -1,21 +1,21 @@
1 -While unzipping a file on Windows, you might encounter a "file path limit" error due to the system’s inability to handle file paths longer than 260 characters.
1 +Unzipping the XWiki distribution on Windows can stop with a "file path too long" error, leaving the extraction incomplete.
2 2  
3 3  === Cause ===
4 4  
5 -This issue arises because the Windows Operating System imposes a [[file path limit to around 260 characters>>https://msdn.microsoft.com/en-us/library/aa365247(VS.85).aspx#maxpath]] in older versions. The file path limit can be exceeded also during file extraction, especially if the file is stored in a deeply nested folder.
5 +Windows limits a full file path to about 260 characters, as described in the [[maximum path length limitation>>https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation]]. The distribution nests its files deeply, so extracting it into a folder that is itself deep in the tree pushes some of those paths past the limit.
6 6  
7 7  === Solution ===
8 8  
9 -To solve this, you can try:
9 +Any one of the following avoids the limit:
10 10  
11 -* Install in a folder that is as close to the root of the drive as possible and uses a small name, e.g. ##C:\xwiki##.
12 -* Install XWiki using the [[cygwin>>https://www.cygwin.com/]] environment that overcomes this limitation.
13 -* In Windows 10 and 11, you can enable long paths by making both following changes:
14 -** In the Windows Registry, set ##EnableLongPaths## to ##1## under ##HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem##.
15 -** In the Group Policy Editor by pressing ##Win + R##, typing ##gpedit.msc##, and navigating to ##Computer Configuration → Administrative Templates → System → File System##. Locate ##Enable Win32 long paths##, double-click it, select "Enabled", and click "Apply". //A system restart is required for the changes to take effect.//
16 -* Use PowerShell command(((
17 -{{code language="none"}}
11 +* Extract the archive close to the root of the drive, into a folder with a short name such as ##C:\xwiki##.
12 +* Extract it with PowerShell:(((
13 +{{code language="powershell"}}
18 18  Expand-Archive -Force C:\path\to\XWiki.zip C:\where\to\extract\XWiki
19 19  {{/code}}
20 20  )))
21 -* Alternatively, you can install a third-party utility. See [[suggestions here>>https://sourceforge.net/directory/file-archivers/windows/]].
17 +* Enable long paths system-wide, which takes both of the changes below and a restart of the computer:
18 +** In the Windows Registry, set ##LongPathsEnabled## to ##1## under ##HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem##.
19 +** In the Group Policy Editor, opened by pressing ##Win + R## and typing ##gpedit.msc##, go to "Computer Configuration", then "Administrative Templates", "System" and "File System"; double-click "Enable Win32 long paths", select "Enabled" and click "Apply".
20 +* Extract it from the [[cygwin>>https://www.cygwin.com/]] environment, which is not subject to the limit.
21 +* Extract it with a third-party archiver, such as one of these [[file archivers for Windows>>https://sourceforge.net/directory/file-archivers/windows/]].
DocApp.Code.DocumentationClass[0]
Related
... ... @@ -1,3 +1,4 @@
1 +* [[Install a Standalone (Demo) Distribution>>doc:documentation.xs.admin.installation.methods.install-standalone-demo-distribution.WebHome]].
1 1  * [[Multiple Instances of XWiki in the Same Container>>documentation.xs.admin.installation.troubleshooting.multiple-instances-container.WebHome]].
2 2  * [[XWiki behind a Proxy Server>>documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.WebHome]].
3 3  * [[SSL Certificate Error>>documentation.xs.admin.installation.troubleshooting.ssl-certificate-error.WebHome]].

Edition of Multiple Instances of XWiki in the Same Container

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.superadmin
1 +XWiki.elenicojocariu
Content
... ... @@ -1,7 +1,8 @@
1 -When running multiple XWiki instances in the same servlet container (e.g., Tomcat or Jetty), you may encounter the following error if multiple instances try to use the same cache domain:
1 +When several XWiki instances are deployed in the same servlet container, such as Tomcat or Jetty, only the first one starts. The others fail while initializing their cache:
2 2  
3 3  {{code language="none"}}
4 4  com.xpn.xwiki.XWikiException: Error number 3 in 0: Could not initialize main XWiki context
5 +Wrapped Exception: Failed to get cache factory component
5 5  ...
6 6  Caused by:
7 7  org.infinispan.jmx.JmxDomainConflictException: Domain already registered org.xwiki.infinispan
... ... @@ -9,15 +9,22 @@
9 9  
10 10  === Cause ===
11 11  
12 -This error occurs because the cache component (Infinispan) attempts to register the same ##JMX## domain for multiple instances, causing a conflict.
13 +XWiki exposes its caches over JMX, and the domain they register under is set in the cache configuration file shipped inside the web application. Every instance deployed from the same distribution therefore asks for the same domain, and the JMX server refuses the second registration.
13 13  
14 14  === Solution ===
15 15  
16 -To resolve the issue, you need to configure each XWiki instance to use a unique ##JMX## domain:
17 +Give each instance a JMX domain of its own:
17 17  
18 -1. Edit ##WEB-INF/cache/infinispan/config.xml## for each XWiki instance.
19 -1. For Infinispan version 7 and above:(((
20 -* Add the <jmx duplicate-domains="true"/> element inside the <cache-container> element to allow multiple domains.
19 +1. Open ##WEB-INF/cache/infinispan/config.xml## in one of the instances, and find the ##jmx## element inside ##cache-container##:(((
20 +{{code language="xml"}}
21 +<jmx enabled="true" domain="org.xwiki.infinispan" />
22 +{{/code}}
21 21  )))
24 +1. Change its ##domain## attribute to a value unique to that instance:(((
25 +{{code language="xml"}}
26 +<jmx enabled="true" domain="org.xwiki.infinispan.intranet" />
27 +{{/code}}
28 +)))
29 +1. Repeat on every other instance in the container, then restart the container.
22 22  
23 -This ensures that each XWiki instance operates with its own JMX domain, preventing the conflict.
31 +On an instance whose caches do not need to be monitored over JMX, setting ##enabled## to ##false## on the same element avoids the conflict as well.
DocApp.Code.DocumentationClass[0]
Related
... ... @@ -1,3 +1,4 @@
1 +* [[Tomcat Troubleshooting>>doc:documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.troubleshooting.WebHome]].
1 1  * [[XWiki behind a Proxy Server>>documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.WebHome]].
2 2  * [[SSL Certificate Error>>documentation.xs.admin.installation.troubleshooting.ssl-certificate-error.WebHome]].
3 3  * [["File Path too Long" on Windows when Unzipping>>documentation.xs.admin.installation.troubleshooting.file-path-long-windows-unzipping.WebHome]].

Summary

Details

Page properties
Content
... ... @@ -1,28 +1,29 @@
1 -Sometimes, XWiki fails to access ##HTTPS## websites, and logs an SSL handshake exception:
1 +XWiki can fail to reach an HTTPS service, such as an extension repository, an LDAP directory or a mail server, and log a PKIX path building failure:
2 2  
3 3  {{code language="none"}}
4 -2017-03-14 20:40:17,494 [http://dwswiki10:8080/xwiki/bin/admin/XWiki/XWikiPreferences?editor=globaladmin&section=XWiki.AddExtensions] ERROR aultExtensionRepositoryManager - Failed to search on repository [store.xwiki.com:xwiki:https://store.xwiki.com/xwiki/rest] with query [org.xwiki.extension.repository.search.ExtensionQuery@78b5e254]. Ignore and go to next repository.
4 +ERROR aultExtensionRepositoryManager - Failed to search on repository [store.xwiki.com:xwiki:https://store.xwiki.com/xwiki/rest] with query [org.xwiki.extension.repository.search.ExtensionQuery@78b5e254]. Ignore and go to next repository.
5 5  org.xwiki.extension.repository.search.SearchException: Failed to search extensions based on pattern []
6 - at org.xwiki.extension.repository.xwiki.internal.XWikiExtensionRepository.search(XWikiExtensionRepository.java:434)
7 7  ...
8 8  Caused by: java.io.IOException: Failed to request [https://store.xwiki.com/xwiki/rest/repository/search?start=0&number=20&q=]
9 - at org.xwiki.extension.repository.xwiki.internal.XWikiExtensionRepository.getRESTResource(XWikiExtensionRepository.java:246)
10 10  ...
11 -Caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
12 - at sun.security.ssl.Alerts.getSSLException(Alerts.java:192)
9 +Caused by: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
13 13  ...
14 -Caused by: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
15 - at sun.security.validator.PKIXValidator.doBuild(PKIXValidator.java:387)
16 -...
17 -Caused by: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
18 - at sun.security.provider.certpath.SunCertPathBuilder.build(SunCertPathBuilder.java:145)
19 -...
20 20  {{/code}}
21 21  
22 22  === Cause ===
23 23  
24 -This usually happens because the [[Java Runtime Environment (JRE)>>dev:Community.SupportStrategy.JavaSupportStrategy.WebHome]] used to run XWiki is too old to validate the SSL certificate of the target server. Specifically, versions of Java 8 older than update 101 do not include the necessary root certificates to validate some HTTPS connections.
15 +The Java runtime validates every HTTPS certificate against its own truststore, and refuses the connection when it cannot build a chain from the certificate the server presents to an authority that truststore holds. That truststore belongs to the Java installation and is unrelated to the authorities the operating system and the browsers trust, which is why the same address can open in a browser on the server and still fail from XWiki. Two situations commonly produce it: a proxy server that inspects TLS traffic and re-signs it with a private authority, and an internal service presenting a self-signed certificate.
25 25  
26 26  === Solution ===
27 27  
28 -Upgrade Java 8 to at least update 101 (no need to jump to Java 9 or higher). You can check your Java version: {{code language="none"}}java -version{{/code}}. Restart your application server (Tomcat, Jetty, etc.) after upgrading Java so that XWiki picks up the new runtime.
19 +Add the missing certificate authority to the truststore of the Java runtime XWiki runs on:
20 +
21 +1. Obtain the certificate of the authority that signed the service's certificate, in ##PEM## or ##DER## form.
22 +1. Import it into the truststore of that Java runtime, which asks for the truststore password (##changeit## unless it was changed):(((
23 +{{code language="bash"}}
24 +keytool -importcert -cacerts -alias my-internal-ca -file my-internal-ca.crt
25 +{{/code}}
26 +)))
27 +1. Restart the servlet container, so that XWiki reads the truststore again.
28 +
29 +Where the Java installation must stay untouched, ##-Djavax.net.ssl.trustStore## and ##-Djavax.net.ssl.trustStorePassword## point the Java runtime at a separate truststore file instead. They are set on the process running XWiki the same way as the [[proxy properties>>doc:documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.configure-proxy.WebHome]].
DocApp.Code.DocumentationClass[0]
Related
... ... @@ -1,3 +1,4 @@
1 +* [[XWiki Behind a Proxy Server>>doc:documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.WebHome]].
1 1  * [[Multiple Instances of XWiki in the Same Container>>documentation.xs.admin.installation.troubleshooting.multiple-instances-container.WebHome]].
2 2  * [[XWiki behind a Proxy Server>>documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.WebHome]].
3 3  * [["File Path too Long" on Windows when Unzipping>>documentation.xs.admin.installation.troubleshooting.file-path-long-windows-unzipping.WebHome]].

Edition of XWiki Behind a Proxy Server

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,1 @@
1 -XWiki behind a Proxy Server
1 +XWiki Behind a Proxy Server
Content
... ... @@ -1,24 +1,9 @@
1 -If your XWiki installation is running behind a proxy server, it will likely fail to search for or install extensions, as the [[Extension Manager>>extensions:Extension.Extension Manager Application]] relies on [[remote repositories>>||anchor="HWhydosomeextensionsfailtoloadwhenusingaproxythatrestrictsInternetaccess3F"]] for this. As a result, you may see ##connection refused## exceptions in the log files.
1 +An XWiki instance that reaches the Internet through a proxy server cannot search for or install extensions until that proxy is configured, because the [[Extension Manager>>extensions:Extension.Extension Manager Application]] fetches them from remote repositories. The log files then fill with ##connection refused## exceptions.
2 2  
3 3  === Cause ===
4 4  
5 -This happens because XWiki, by default, cannot access the internet through the proxy without proper configuration.
5 +XWiki makes its outgoing HTTP calls through Apache HttpClient, which reads the standard Java proxy system properties. Nothing sets those properties by default, so XWiki tries to open the connection directly and the network refuses it.
6 6  
7 7  === Solution ===
8 8  
9 -To configure XWiki to work behind a proxy, you need to add the relevant proxy properties/settings to your system environment. XWiki uses the default Java proxy configuration via Apache HttpClient. For more details, refer to the [[Java Networking and Proxies documentation>>https://docs.oracle.com/javase/6/docs/technotes/guides/net/proxies.html]].
10 -
11 -* If you [[installed XWiki using Tomcat 8+>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]]:(((
12 -1. Open the {{code language="none"}}setenv.sh{{/code}} (for Linux/Unix) or {{code language="none"}}setenv.bat{{/code}} (for Windows) file from your Tomcat installation’s {{code language="none"}}bin{{/code}} directory with an editor and add:(((
13 -* For Linux/Unix: {{code language="none"}}CATALINA_OPTS="$CATALINA_OPTS -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777"{{/code}}
14 -* For Windows: {{code language="none"}}set CATALINA_OPTS=%CATALINA_OPTS% -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777{{/code}}
15 -)))
16 -1. Restart Tomcat.
17 -)))For more tips and configuration options, see the ##RUNNING.txt## / ##RUNNING.md## file from the Tomcat distribution.
18 -* If you [[installed a standalone (demo) distribution>>documentation.xs.admin.installation.methods.install-standalone-demo-distribution.WebHome]]:(((
19 -1. Open the {{code language="none"}}start_xwiki.bat{{/code}} (for Windows) or {{code language="none"}}start_xwiki.sh{{/code}} (for Linux/Unix) with an editor and add:(((
20 -* For Linux/Unix: {{code language="none"}}XWIKI_OPTS="$XWIKI_OPTS -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777 -Dhttps.proxyHost=proxy.mycompany.com -Dhttps.proxyPort=7777"{{/code}}
21 -* For Windows: {{code language="none"}}set XWIKI_OPTS=%XWIKI_OPTS% -Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=7777{{/code}}
22 -)))
23 -1. Restart XWiki.
24 -)))
9 +[[Configure XWiki to use the proxy server>>doc:documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.configure-proxy.WebHome]], then [[check that the configuration reached it>>doc:documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.debug-configuration.WebHome]].
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,11 +1,3 @@
1 1  == Why do some extensions fail to load when using a proxy that restricts Internet access? ==
2 2  
3 -If your proxy server only allows partial access to the Internet, XWiki’s [[Extension Manager>>extensions:Extension.Extension Manager Application]] may fail to retrieve available extensions. This happens because XWiki needs to connect to specific external repositories: ##store.xwiki.com##, ##extensions.xwiki.org##, ##nexus.xwiki.org##. Note: one is ##.com##, the others are ##.org##. Make sure all three are accessible through your proxy.
4 -
5 -== What if my proxy server requires authentication? ==
6 -
7 -You can provide proxy credentials using Java system properties in your startup script: {{code language="none"}}-Dhttps.proxyUser{{/code}} and {{code language="none"}}-Dhttps.proxyPassword{{/code}} (and the ##http## alteratives).
8 -
9 -== Is XWiki configured properly to see my proxy? ==
10 -
11 -If you still have errors, cannot download extensions with the [[Extension Manager>>extensions:Extension.Extension Manager Application]], or simply want to check whether the proxy settings were applied, you can [[debug proxy configuration>>documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.debug-configuration.WebHome]].
3 +The [[Extension Manager>>extensions:Extension.Extension Manager Application]] reads from three hosts, so a proxy that allows only some of them leaves part of the catalogue unavailable: ##store.xwiki.com##, ##extensions.xwiki.org## and ##nexus.xwiki.org##. Note that the first is a ##.com## and the other two are ##.org##.
Related
... ... @@ -1,3 +1,4 @@
1 +* [[SSL Certificate Error>>doc:documentation.xs.admin.installation.troubleshooting.ssl-certificate-error.WebHome]].
1 1  * [[Multiple Instances of XWiki in the Same Container>>documentation.xs.admin.installation.troubleshooting.multiple-instances-container.WebHome]].
2 2  * [[SSL Certificate Error>>documentation.xs.admin.installation.troubleshooting.ssl-certificate-error.WebHome]].
3 3  * [["File Path too Long" on Windows when Unzipping>>documentation.xs.admin.installation.troubleshooting.file-path-long-windows-unzipping.WebHome]].

Edition of Debug Proxy Configuration

Summary

Details

Page properties
Content
... ... @@ -1,32 +1,12 @@
1 -To check that your proxy configuration is properly read by XWiki and confirm whether the server can access the Internet:
1 +Searching for an extension tells you whether XWiki reaches the Internet through the proxy server you [[configured>>doc:documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.configure-proxy.WebHome]]; see [[XWiki Behind a Proxy Server>>doc:documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.WebHome]] for the cause it points at.
2 2  
3 -1. [[Create a Page>>documentation.xs.user.base.page.create.WebHome]] (for example: ##Sandbox.ProxyDebug##).
4 -1. [[Edit the Page with the Wiki editor>>documentation.xs.user.base.page.edit-page.edit-wiki-editor.WebHome]].
5 -1. Insert the following Groovy script to list environment variables and Java system properties:(((
6 -{{code language="groovy"}}
7 -{{groovy}}
8 -println "== Environment Variables =="
9 -System.getenv().each { name, value -> println "Name: {{{$name}}} = Value {{{$value}}}" }
10 -println ""
11 -println "== Java System Properties =="
12 -System.getProperties().each { name, value -> println "Name: {{{$name}}} = Value {{{$value}}}" }
13 -{{/groovy}}
14 -{{/code}}
3 +1. Open the "Extensions" section of the wiki administration.(((
4 +{{image reference="administration-extensions-section.png" size="extra" alt="The Extensions entry of the wiki administration menu."/}}
15 15  )))
16 -1. Insert the following Velocity test to check HTTP connectivity and if your XWiki instance is able to access the Internet:(((
17 -{{code language="velocity"}}
18 -== Test HTTP Access ==
19 -Your XWiki server's IP is:
20 -{{velocity}}
21 -$xwiki.getURLContent("http://httpbin.org/ip")
22 -{{/velocity}}
23 -
24 -== Test HTTPS Access ==
25 -Your XWiki server's IP is:
26 -{{velocity}}
27 -$xwiki.getURLContent("https://httpbin.org/ip")
28 -{{/velocity}}
29 -
30 -{{/code}}
6 +1. Type the name of an extension in the search field.(((
7 +{{image reference="extension-search-field.png" size="large" alt="The search field of the Extensions administration section."/}}
31 31  )))
32 -1. Save the Page and notice the information on the Page.
9 +1. Click the search button.
10 +1. Read the result: the extensions listed were fetched from the remote repositories, so XWiki reaches them through the proxy server.(((
11 +{{image reference="extension-search-results.png" size="extra" alt="The extension search listing extensions fetched from the remote repositories."/}}
12 +)))
administration-extensions-section.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +58.1 KB
Content
extension-search-field.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +19.1 KB
Content
extension-search-results.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +61.1 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,7 +1,17 @@
1 -== Why can’t I execute the script? ==
1 +== The search lists nothing, or reports an error naming a repository. What does that mean? ==
2 2  
3 -You need [[programming rights>>Documentation.AdminGuide.Access Rights.Permission types.WebHome||anchor="HProgrammingRights"]] to run scripts.
3 +The connection did not go through: either the proxy properties never reached XWiki, or the proxy server does not allow that host. Re-check the [[proxy configuration>>doc:documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.configure-proxy.WebHome]], then the host list the repositories need.
4 4  
5 -== Can I use any other service than the "httpbin" service to test Internet connectivity? ==
5 +== How do I see every property and environment variable the running XWiki reads? ==
6 6  
7 -Yes, you can use any other service that returns a valid response over HTTP or HTTPS, including {{code language="none"}}https://www.google.com{{/code}}. Using ##httpbin.org## is convenient because it returns your public IP address, which makes it easy to confirm that the request goes through the proxy.
7 +The command line shows what the startup script passes, which is not always what the Java runtime ends up with, so it is worth reading the values from inside XWiki. Put the following in a page, which takes [[programming rights>>doc:Documentation.AdminGuide.Access Rights.Permission types.WebHome||anchor="HProgrammingRights"]]:
8 +
9 +{{code language="none"}}
10 +{{groovy}}
11 +println "== Environment Variables =="
12 +System.getenv().each { name, value -> println "Name: {{{$name}}} = Value {{{$value}}}" }
13 +println ""
14 +println "== Java System Properties =="
15 +System.getProperties().each { name, value -> println "Name: {{{$name}}} = Value {{{$value}}}" }
16 +{{/groovy}}
17 +{{/code}}

Edition of Installation

Summary

Details

Page properties
Content
... ... @@ -62,7 +62,7 @@
62 62  
63 63  == Running XWiki behind a proxy server ==
64 64  
65 -See [[XWiki behind a Proxy Server>>documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.WebHome]].
65 +See [[XWiki Behind a Proxy Server>>documentation.xs.admin.installation.troubleshooting.xwiki-proxy-server.WebHome]].
66 66  
67 67  === Debugging proxy configuration issues ===
68 68  
... ... @@ -70,14 +70,16 @@
70 70  
71 71  == Unsupported major.minor version 51.0 ==
72 72  
73 -This is because starting with version 6.0, XWiki requires Java 7 and you're using Java 6. You need to upgrade your Java version.
73 +See [[XWiki Startup Failure after a Required Java Upgrade>>documentation.xs.admin.upgrade.troubleshooting.xwiki-startup-failure-java-upgrade.WebHome]].
74 74  
75 -See [[Install XWiki without Internet>>documentation.xs.admin.installation.install-offline.WebHome]].
75 +== Installing without an Internet connection ==
76 76  
77 +See [[Install XWiki without Internet Connection (XIP Package)>>documentation.xs.admin.installation.install-offline.WebHome]].
78 +
77 77  == Getting an error about SSL certificate ==
78 78  
79 -See [[]].
81 +See [[SSL Certificate Error>>documentation.xs.admin.installation.troubleshooting.ssl-certificate-error.WebHome]].
80 80  
81 81  == "File path too long" on Windows when unzipping ==
82 82  
83 -See [[]].
85 +See [["File Path too Long" on Windows when Unzipping>>documentation.xs.admin.installation.troubleshooting.file-path-long-windows-unzipping.WebHome]].
Aug 19, 2026, 3:42:02 PM

Approved by Eleni Cojocariu

Approvers

Approvers have not been explicitly defined for this Change Request. Approvers will be based entirely on approval rights.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected