When the package server cannot be reached
This page is for administrators who see a download error during an installation. It explains how the installer
retries, what each message means, where to find the details, and what to do. The behavior is that of
eZStepSiteTypes in kernel/setup/steps/ezstep_site_types.php (6.0.15).
Contents
How the installer retries
Every download of the setup, the index as well as each package, is tried up to DownloadAttempts times (default 3),
waiting DownloadRetryDelays[] seconds between attempts (default 2, then 5). One attempt may take
DownloadTimeout seconds (300) and wait DownloadConnectTimeout seconds (30) for the connection. A failed attempt
leaves no partial file behind (Package server settings).
Retries exist because "a package server that is being republished answers with errors for a few minutes" (changelog 6.0.15): while GitHub Pages deploys a new version of the site, a request can fail (The package server on GitHub).
Not retried: a download whose file cannot be written locally ("Cannot write to file"), because waiting does not help.
The messages
| Message on the Site package step or the command line | Meaning |
|---|---|
| "Retrieving remote site packages list failed. You may upload packages manually." | The index could not be downloaded and there is no var/storage/packages/7x/index.xml. Imported site packages are still listed |
| "Download of package 'name' failed after N attempts: reason. You may upload the package manually." | Every attempt to download a package failed; the reason is that of the last attempt |
| "Download of package 'name' failed: reason. You may upload the package manually." | The download failed once and was not retried |
| "Download of package 'name' failed. You may upload the package manually." | A required package is not imported and the index has no entry for it (or no index could be read) |
| "Invalid package" | The file arrived, but importing it failed: not a package, an invalid name, or an archive the import refuses |
With an error, the step also shows "Remote repository URL:" with the address it used, the value of
RemotePackagesIndexURL. Check it first.
The reasons
The reason in the message tells you where it failed:
| Reason | What it means | Likely cause |
|---|---|---|
curl error 6: Could not resolve host ... | the host name was not found | no DNS on the server, or a typo in RemotePackagesIndexURL |
curl error 7: ..., curl error 28: ... | no connection, or a timeout | outgoing HTTPS blocked by a firewall, a proxy is needed, or the network is slow |
cannot resolve the host '...' | the same, without the curl extension | as above |
HTTP 404 | the file is not there | a wrong release folder, a package name not in the index, or a deployment in progress |
HTTP 403, HTTP 5xx | the server refused or failed | a proxy refusing, or the server being republished |
the server sent an empty file | 200 with no content | an intercepting proxy, or a deployment in progress |
the file is truncated, N bytes expected | the transfer stopped early | an unstable connection, or DownloadTimeout too short for a large package |
the file is not a gzip-compressed package | an .ezpkg that is not gzip data | a proxy or captive portal answered with a web page |
Each reason ends with the number of bytes received, for example "HTTP 404, 9379 bytes received".
Where to look
| Where | What you find |
|---|---|
var/log/setup.log | one warning per failed attempt: "Download of url, attempt n of N failed: reason; trying again in s s" |
the debug output, var/log/warning.log | the same warnings, and "Download of package 'name' from 'url' failed after N attempt(s): reason" |
var/log/kickstart.log | the run of the kickstarter (The kickstarter, 6.9) |
From the server itself, test what the installer would see:
# the index of the release this installation uses
curl -sS -o /dev/null -w '%{http_code} %{size_download} bytes\n' \
https://exponential.packages.exponential.earth/exponential/6.0/6.0.15/index.xml
through the proxy of site.ini [ProxySettings], if you have one
curl -sS -x http://proxy.example.com:3128 -o /dev/null -w '%{http_code}\n' \
https://exponential.packages.exponential.earth/exponential/6.0/6.0.15/index.xmlRun it as the user that runs PHP. 200 means the server is reachable from there; then look at the package address
named in the message.
What to do
Work down the list:
- To do: Read the address. Is "Remote repository URL:" the release folder you expect? A typo, an
http://mirror that is gone, or an emptiedRemotePackagesIndexURL(whose fallback builds a folder name that does not exist, see Package server settings) all end in errors. - To do: Open the address in a browser or with
curlfrom the server, as above. - To do: Wait a few minutes and try again when the server answered
404or an error for a file that exists in the listing: a deployment may be running. Its progress is under the repository's Actions. - To do: Set the proxy in
site.ini [ProxySettings](ProxyServer, andUser,Passwordif needed) when the server can only reach the internet through one. The setup's downloads over curl use it. - To do: Allow outgoing HTTPS to
exponential.packages.exponential.earthin the firewall, if your hosting restricts outgoing connections. - To do: Raise the limits for a slow connection:
DownloadTimeout,DownloadAttempts(Overriding the settings). - To do: Upload the package by hand: download it elsewhere, then use Upload package on the Site package step,
or
php ezpm.php import(Downloading a package by hand). - To do: Install offline: import every package first (Offline installs and mirrors).
For the console install, a stop while fetching packages is covered in The console install, 7.11 and Troubleshooting, 12.8.
Tip
On a server you install often, run exp:install --dry-run first. It downloads the site package and its
requirements into a temporary repository and stops before writing anything, so a download problem shows up before
the install starts (The console install, 7.6).
In ezupdate
ezupdate's Package servers page uses its own download (extension/ezupdate/classes/ezupdatepackageservers.php):
HTTPS only, a 15 second connection limit, 300 seconds per transfer, the proxy of site.ini [ProxySettings] ProxyServer, and no retries. Its messages:
| Message | Meaning |
|---|---|
| "Could not fetch url: reason" | the transfer failed; the reason is curl's |
| "The server did not answer with a package index." | the answer was not XML with a <packages> root |
| "The PHP curl extension is needed to reach a server." | PHP has no curl |
| "The address must be an https:// URL." / "The package address must be an https:// URL." | a server or package address with another scheme |
See Package servers in ezupdate.
Related pages
- Site packages: start here
- The package server
- Package server settings
- Offline installs and mirrors
- The setup wizard, 5.3.8 Site package
- When something goes wrong
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.