Troubleshooting
Setup
Start with pnpm check:prereqs. It names each missing prerequisite and prints the fix.
| Symptom | Cause | Fix |
|---|---|---|
pnpm setup changes your shell profile instead of checking prerequisites | setup is a built-in pnpm command | Use pnpm check:prereqs |
pnpm: command not found, or the wrong pnpm version | pnpm is missing, or Corepack isn't enabled | corepack enable, or npx get-pnpm; the pinned version is in package.json → packageManager |
cargo: command not found just after installing Rust | The terminal was opened before rustup updated PATH | Open a new terminal. pnpm check:prereqs also looks in ~/.cargo/bin |
link.exe not found or LNK1181 on Windows | Microsoft C++ Build Tools are missing, or the Rust toolchain is GNU instead of MSVC | Install the "Desktop development with C++" workload; check that rustup show lists x86_64-pc-windows-msvc |
webkit2gtk-4.1 not found on Linux | WebKitGTK development files are missing | Install the apt packages in DEVELOPMENT.md |
Port 1430 is in use | Another Apollo DM dev server is already running | Stop it. V1's dev server uses port 1420, so it doesn't conflict |
| Every file shows as modified after cloning on Windows | Line endings were converted | .gitattributes stores text with LF; run git add --renormalize . and check that you aren't overriding core.autocrlf per repository |
The first pnpm dev seems stuck | It is compiling every Rust dependency (about 4–5 minutes on the reference machine) | Wait; later runs take seconds |
| The window heading shows "Could not reach the native shell" | The UI was opened in a browser (pnpm dev:web), where Tauri commands don't exist | Use pnpm dev |
Downloads
These are the messages the engine reports when a download waits or fails. The app shows them once the downloads list is built (#59). What the engine does in each case is in ENGINE_INTERNALS.md.
| Message or status | Cause | What to do |
|---|---|---|
| Retrying, with "Trying again (2 of 5)." | A request failed, for the reason shown, and is tried again after a wait; a start gives up after 5 tries | Nothing. If the server can't be reached at all (the name doesn't resolve, or the connection is refused or times out), the download fails after those 5 tries: check the link and your connection, then retry |
| Retrying, with "Retrying automatically (1 of 2)." | The download failed in a way worth retrying, and the engine waits before starting it again | Nothing. If it ends as Failed, the message says why |
| Stalled | No data has come from the server for 15 seconds | Nothing at first: after 30 seconds the connection is reset and tried again. If it keeps stalling, check the network connection |
| "The server is rate limiting requests. …" (HTTP 429) or "The server is temporarily unavailable or overloaded." (HTTP 503) | The server asked clients to slow down | Apollo Download Manager waits as long as the server asks, up to 10 minutes, and uses fewer connections. It remembers that for the server until the app quits, so later downloads from it don't ask for more. If it still fails, try again later |
| "The file was not found on the server. The link may have expired." (HTTP 404) | The address is wrong or no longer valid | Get a new link from the site |
| "The server requires a user name and password." (HTTP 401) | The server wants a login, or refused the one sent | The login window opens (loginRequired, #249); a new login is retried with it |
| "The server denied access to the file. …" (HTTP 403) | Refused, or the link expired | Get a new link |
| "The server redirected to an insecure http:// address, which isn't allowed. (a redirect from https:// to http://, …)" | A secure link redirected to an unencrypted address. Apollo Download Manager refuses it, so nothing is downloaded over a connection that could be read or changed on the way | The download stops and asks: "Continue over http" in its details panel goes on for that download only (#67). Otherwise ask the site for an https:// link |
| "The address, or a redirect, uses a protocol that is not allowed. (a redirect to ftp://, …)" | The link redirected to another kind of address, such as ftp:// or file://. Redirects may only go to http:// and https:// | Use the address the redirect named directly, if it is one Apollo Download Manager downloads |
| "The server redirected too many times. (more than 10 redirects)" | The link redirects in a loop, or through more than 10 addresses | Open the link in a browser to see where it ends, and use that address |
| "The download link expired. Get a fresh link from the browser." | The link worked when the download started, then the server refused it. Signed links, such as those of cloud storage, expire after a set time | Copy the link again from the site or the browser and start the download with it |
| "The downloaded file doesn't match its SHA-256 checksum (the file's is …)." (or MD5, SHA-1, SHA-224, SHA-384, SHA-512) | The bytes that arrived aren't the file the checksum describes: the checksum was copied wrong or belongs to another version, or the file was damaged on the way | Check that the checksum is the one the site gives for this exact file and version. The part file (<name>.vdmpart) is kept beside the destination, so it can be inspected; retrying downloads the file again |
| "The downloaded file's piece n of m doesn't match its trusted hash, even after fetching it again 2 times: the server sends bad data." | A server or mirror sends the same wrong bytes for one part of the file | Retry later, or from another mirror. The part file is kept for inspection; retrying downloads the file again |
| "The downloaded file's piece n of m doesn't match its trusted hash, in two downloads of the whole file: …" | The same, from a server that can't send part of a file, so Apollo Download Manager downloaded the whole file twice | As above |
| "Apollo Download Manager downloaded this Metalink file but couldn't add its files: …" | The download was a Metalink file (by its name, or what the server called it), and Apollo Download Manager couldn't use it: the reason follows, such as an unsafe file name, a document type declaration, or no source Apollo Download Manager can download | The Metalink file is kept. If the reason is a source Apollo Download Manager can't use, such as only a torrent, download the files another way. Otherwise ask the site for a correct Metalink file |
| "The Metalink file names a file Apollo Download Manager won't create: …" | A file's name in it climbs out of the folder (..), is absolute, or uses a name Windows reserves or a character it forbids | Don't use this Metalink file: it may be malicious. Ask the site for a correct one |
| "The Metalink file declares a document type, which Apollo Download Manager refuses: …" | The document starts with <!DOCTYPE, which could define entities that expand without limit or read other files | As above |
| "The file's trusted piece list doesn't fit it: …" | The piece list (from a Metalink file) describes a file of another size than the server sends | Get the Metalink file and the download from the same place and version |
| "The file changed on the server during download, twice: …" | The file on the server was replaced while it downloaded. Apollo Download Manager started over once with the new file, and it changed again | Retry later, when the site has finished updating the file |
| "The server name could not be resolved. Check the link's spelling, the proxy's address if one is set, and the internet connection. Some servers can be reached only over IPv6, which this network may not have." | No network, a name that doesn't exist (in the link, or the proxy's), or a server with only an IPv6 address (AAAA record) on a network without IPv6 internet: Windows' resolver then returns no address, and curl.exe fails the same way (#250) | Check the network connection and the address; Resolve-DnsName <host> (Windows) or dig <host> A AAAA shows which addresses the name has. Each start retries it inside the download first; a start that never reached the server isn't started again on its own (#245) |
| "This computer has no network connection to the server. Check the Wi-Fi or the cable. Some servers can be reached only over IPv6, which this network may not have." | A connect failed because this computer has no route to the server: the OS reports the network down or unreachable (WSAENETUNREACH and similar, read from libcurl's CURLINFO_OS_ERRNO). Wi-Fi off, a cable out, or an IPv6-only address on a network without IPv6. It's never taken for a server that refuses this computer (#335) | Check the network connection. It's retried as a transient failure, and a download that already had bytes is ridden out for about 5 minutes (#317); a start that never reached the server isn't started again on its own (#245) |
| "The website's security certificate has expired, so the connection was refused. …" | The TLS backend reported an expired (or not yet valid) certificate: OpenSSL's "certificate has expired", Schannel's "not time valid" or SEC_E_CERT_EXPIRED (#252). Verification is never turned off | The site's owner renews it. For a server of your own, check the computer's date and time too |
| "The website's security certificate is for another website, so the connection was refused. …" | The certificate doesn't name the link's host: OpenSSL's "no alternative certificate subject name matches", Schannel's SEC_E_WRONG_PRINCIPAL | Check the link's host name |
| "The website's security certificate isn't trusted on this computer, so the connection was refused. …" | No trusted authority issued it: self-signed, an unknown issuer, or an incomplete chain (OpenSSL's "unable to get local issuer certificate", Schannel's SEC_E_UNTRUSTED_ROOT) | Check for a proxy or security program that intercepts TLS. For a private server, add its CA to the system trust store |
| "The website's security certificate was refused, so the connection was closed. …" | Any other refusal: revoked (Schannel checks revocation; OpenSSL without a CRL doesn't, #69), or not for server authentication | The site has to fix its certificate |
| "The file wasn't found on the server." | An FTP server has no file at that path (its reply 550) | Check the path in the link; FTP paths are often case-sensitive |
| "The server refused the login. Check the user name and password." | An FTP server refused the user name or password (530, libcurl's CURLE_LOGIN_DENIED). The login window opens (#249) | Check the login. Without one, Apollo Download Manager logs in as anonymous, which many servers refuse |
| "The server doesn't let this user read the file." | The login worked, but the server refused the file: FTP's refused access (CURLE_REMOTE_ACCESS_DENIED), SFTP's permission denied. No login window, as a new password won't help | Ask the server's owner for access |
| "The server's identity isn't confirmed yet. Check that its host key fingerprint is SHA256:…, then trust it to continue." | The first SFTP download from a server: SSH has no certificate authority, so Apollo Download Manager asks before trusting a server's key. Nothing was sent: no login, no file name | Compare the fingerprint with the one the server's owner publishes (for example with ssh-keygen -lf on the server). The window asks "Trust this server?": choose "Trust and continue" only if they match |
| "The server's host key changed (it was SHA256:…, it is now SHA256:…). This could be an attack, so the connection was refused." | The SFTP server presents another key than the one trusted before. A reinstalled server does this, and so does an attacker in the middle | Ask the server's owner whether the key changed, and why. Apollo Download Manager never trusts a changed key: the old entry must be removed from known_hosts in the app's data folder by hand, after checking |
| "The server refused the login. Check the user name and password." (SFTP; its own words under Technical details) | The SFTP user name, password or private key was refused, the key's passphrase is wrong, or no user name was given. The login window opens (#249) | Check the login. A private key must be one the server lists for that user |
| "The server can't encrypt the connection, and this download requires encryption." | The download requires encryption, and the FTP server doesn't offer FTPS (AUTH TLS was refused). Nothing was sent: the login stayed on this computer | Ask the site for an ftps:// link or an https:// one. Only download without encryption if the login and the file may be read on the network |
| "The proxy refused the connection. Check its user name and password in Settings, Proxy." | The proxy refused its login (407, or a SOCKS5 refusal), or refused to connect to the server | Check the proxy's user name and password in Settings, Proxy, then retry. Ask the proxy's administrator whether it allows the server |
| "…SFTP can't go through an HTTPS proxy…" or "Torrents can't go through an HTTPS proxy." | An HTTPS proxy is set, and SFTP and torrents can't use one | Choose an HTTP or SOCKS5 proxy in Settings, Proxy, if your network has one |
| "There is not enough disk space." | The disk filled up during the download. What was downloaded is kept (#74) | Free some space, then retry: the download goes on from where it stopped |
| "Apollo Download Manager isn't allowed to write to that location." | The download's folder stopped accepting writes: its permissions changed, or the drive became read-only. What was downloaded is kept (#74) | Give your user write access to the folder again, then retry: the download goes on from where it stopped |
| "the transfer engine stopped unexpectedly", "the transfer engine stopped responding and was restarted" or "the transfer engine was restarted", on a Queued download | The engine crashed, hung or was restarted. The download waits, and resumes from where it was saved once the engine runs again (#58) | Nothing. If it happens again, report it with the engine's log |
The engine is unavailable (ENGINE_UNAVAILABLE), and downloads wait | The engine crashed more than 5 times in 5 minutes, so it isn't started again on its own | Use "Restart transfer engine"; the waiting downloads then resume. If it keeps crashing, report it with the engine's log |
The engine is missing (ENGINE_MISSING) or doesn't match the app (ENGINE_INCOMPATIBLE) | velocity-transfer isn't beside the app, or is from another build | Reinstall. In development, run pnpm dev, which builds it first (pnpm dev:engine) |
| Torrents wait, and the torrent helper is missing or doesn't match the app | velocity-torrent isn't beside the app, or is from another build | As for the engine. In development, pnpm dev:engine builds it, once libtorrent is built (BUILDING_NATIVE.md) |
| The extension's popup says "The connection to Apollo DM is not set up" | Apollo DM's native host isn't registered with that browser, or was registered for another copy of Apollo DM | In Apollo DM, Settings, Browser, choose Register for that browser, then reload the extension (BROWSER_EXTENSION.md) |
| The extension's popup says "Apollo Download Manager is not running" or "was started but didn't answer in time" | The native host starts the app in the tray when it isn't running (#322) and waits up to 10 seconds. It found no app beside it, or the app didn't answer in time, so the browser downloads the file itself | Try the link again once the app is open. If it never starts, reinstall it, so the native host and the app are in the same folder |
| Settings, Browser says the browser connection program isn't installed | velocity-native-host-v2 isn't beside the app | Reinstall. In development, pnpm dev:engine builds it |
| A private torrent finds no peers after the app restarts | Its trackers, which can carry a passkey, aren't kept across a restart; the keychain (#70) holds downloads' logins only | Add the torrent again from its .torrent file or magnet link |
| "Apollo Download Manager doesn't keep logins, custom headers or SSH keys after it closes. Resume this download to enter its login again." on a Paused download | The download had a login, headers or a key, which aren't saved unless you ticked "Remember this login" (#70) | Resume it and enter the login again; tick "Remember this login" when adding it next time |
| "The system keychain couldn't be read, so this download's saved login isn't available." | The login was remembered, but the keychain didn't answer: on Linux, no Secret Service is running, or it is locked | Unlock or start your keyring (GNOME Keyring, KWallet), then restart Apollo Download Manager; or resume and enter the login again |
| "The login wasn't remembered: The system keychain isn't available…" after adding | The system has no keychain Apollo DM can use (on Linux, no Secret Service); the download was added, and its login is kept in memory only | Add it again later with the keyring running, or enter the login after a restart |