aria2c: command not found / 'aria2c' is not recognized
Symptom: The shell says aria2c: command not found, 'aria2c' is not recognized, or yt-dlp reports “aria2c is not installed. please install it first.”
Cause: aria2 is not installed, or its folder is not on your PATH.
Fix: Install it, then reopen the terminal so PATH refreshes.
sudo apt install aria2 # Debian/Ubuntu
brew install aria2 # macOS
winget install aria2.aria2 # Windows (or scoop/choco)
aria2c --version
Expected: aria2c --version prints a version such as 1.37.0.
Windows: installed aria2 but the terminal still can't find it
Symptom: You unzipped aria2 but every new terminal says the command is unknown.
Cause: The folder holding aria2c.exe was never added to the Path environment variable.
Fix: Add the folder to Path and open a new terminal (existing ones keep the old environment).
# Example folder: C:\aria2
setx PATH "%PATH%;C:\aria2"
Expected: A freshly opened CMD/PowerShell finds aria2c.
error while loading shared libraries: libxml2.so.2 / libcares.so.2
Symptom: aria2c exits immediately with a missing shared library.
Cause: Required libraries are absent, or the binary doesn't match your system.
Fix: Install the dependencies provided by your distro.
sudo apt install libxml2 libc-ares2 libssh2-1 libsqlite3-0 zlib1g
# Fedora
sudo dnf install libxml2 c-ares libssh2 sqlite zlib
# Arch
sudo pacman -S aria2 # reinstalls with its deps
Expected: aria2c --version runs without a library error.
Windows: “The code execution cannot proceed because zlib1.dll/libssh2.dll was not found”
Symptom: Opening aria2c.exe pops a missing-DLL error.
Cause: You moved aria2c.exe out of the ZIP folder, away from its bundled DLLs.
Fix: Keep the whole extracted folder together and add that folder to Path.
Expected: aria2c starts and prints its version.
macOS: “cannot be opened because the developer cannot be verified”
Symptom: macOS (Gatekeeper) refuses to run the downloaded binary.
Cause: The binary is quarantined because it wasn't signed/notarized.
Fix: Prefer Homebrew, or remove the quarantine attribute.
brew install aria2
# or, for a manually downloaded binary:
xattr -d com.apple.quarantine ./aria2c
Expected: Gatekeeper allows the binary to run.
Windows Defender / SmartScreen blocks aria2c.exe
Symptom: “Windows protected your PC” or the file is deleted shortly after download.
Cause: Unsigned CLI binaries are sometimes flagged heuristically (false positive).
Fix: Download only from the official GitHub releases, verify the checksum, and allow the file; or install via winget/scoop/choco.
winget install aria2.aria2
# verify the downloaded archive against the release checksums
Expected: aria2c runs and is not removed.
Docker: container exits immediately, or the RPC port isn't reachable
Symptom: The container restarts in a loop, or nothing answers on port 6800.
Cause: Bad entrypoint/command, missing config, or the RPC bound to localhost only inside the container.
Fix: Check the logs; ensure --enable-rpc, rpc-listen-all=true, and the port is published.
docker compose logs -f aria2
docker compose ps
# the service must map: ports: ["6800:6800"]
Expected: curl http://localhost:6800/jsonrpc returns a JSON-RPC response.
aria2c: unable to verify certificate (SSL error)
Symptom: HTTPS downloads fail with a certificate verification error.
Cause: Outdated root CA certificates, or a self-signed/internal certificate.
Fix: Update the CA bundle, or point aria2 at one; for internal sites add the CA.
sudo apt install ca-certificates # Debian/Ubuntu
aria2c --ca-certificate=/etc/ssl/certs/ca-certificates.crt URL
# Only if you trust the source and cannot install the CA:
# aria2c --check-certificate=false URL
Expected: The download starts without the certificate warning.
SSL/TLS handshake failure / “openssl error:00000000”
Symptom: Connection aborts during the TLS handshake; no data is transferred.
Cause: Old TLS stack, an intercepting proxy/antivirus, or an unsupported protocol version.
Fix: Update aria2 and your OS; test without a proxy; try a different network.
Expected: The handshake completes and the download proceeds.
--ca-certificate seems to be ignored (Windows/macOS)
Symptom: Specifying --ca-certificate has no effect.
Cause: The Windows (WinTLS) and macOS (AppleTLS) backends don't support that option; they use the OS trust store.
Fix: Import the certificate into the OS trust store instead.
Expected: HTTPS succeeds using the OS-trusted certificate.
HTTP 403 Forbidden
Symptom: The server returns 403 and the download stops.
Cause: The file needs session cookies, a Referer, or a browser User-Agent (hotlink protection).
Fix: Pass cookies and headers.
aria2c --header="Cookie: session=..." --referer="https://example.com/page" URL
aria2c --load-cookies cookies.txt URL
aria2c --user-agent="Mozilla/5.0" URL
Expected: The server returns 200 and the transfer begins.
HTTP 404 Not Found (exit code 3)
Symptom: aria2 exits with code 3 and repeats “resource not found”.
Cause: The URL is wrong, expired, or the file was removed (common with signed links).
Fix: Get a fresh URL, and set a retry ceiling to fail fast.
aria2c --max-tries=3 --max-file-not-found=1 URL
Expected: aria2 stops quickly instead of looping, or succeeds with the new URL.
HTTP 429 Too Many Requests
Symptom: The server rate-limits you after a burst of requests.
Cause: Too many parallel connections or files in a short window.
Fix: Reduce connections/concurrency and add delays.
aria2c -x 4 -s 4 --max-concurrent-downloads=2 --retry-wait=10 URL
Expected: Requests stay under the limit and downloads complete.
HTTP 503 Service Unavailable
Symptom: The server is temporarily overloaded or in maintenance.
Cause: Transient server-side load or throttling.
Fix: Wait and retry; --retry-wait makes aria2 retry 503 automatically.
aria2c --retry-wait=15 --max-tries=10 URL
Expected: aria2 waits and retries until the server recovers.
HTTP 401 Unauthorized / “HTTP authorization failed” (exit code 24)
Symptom: aria2 reports an authorization failure.
Cause: Wrong or missing credentials (including Basic/Bearer auth).
Fix: Provide credentials via user/pass or an Authorization header.
aria2c --http-user=user --http-passwd=pass URL
# or embed in the URI: https://user:pass@host/file
# or a token header:
aria2c --header="Authorization: Bearer TOKEN" URL
Expected: The server authenticates and starts sending data.
Too many redirects (exit code 23)
Symptom: aria2 aborts with “too many redirects”.
Cause: A redirect loop or a CDN requiring cookies/headers.
Fix: Follow the final URL directly, or supply cookies and a Referer.
Expected: aria2 reaches the final 200 response.
“Remote server did not support resume” (exit code 8)
Symptom: You use -c but aria2 refuses to continue.
Cause: The server ignores byte-range requests, or the file changed (different size/ETag).
Fix: Restart the download without -c, or from a mirror that supports ranges.
aria2c URL # fresh download (no -c)
aria2c -x 16 -s 16 URL # from a range-capable mirror
Expected: A full download completes.
Timeout (exit code 2)
Symptom: aria2 gives up with a timeout.
Cause: A slow/unstable server or a too-short timeout.
Fix: Raise timeouts and retries; drop stalled connections.
aria2c --timeout=60 --connect-timeout=30 --max-tries=5 --retry-wait=5 -c URL
Expected: aria2 retries and resumes instead of aborting.
FTP: login failed / “FTP command failed” (exit code 21)
Symptom: FTP transfers fail with an auth or command error.
Cause: Wrong credentials, or a firewall blocking passive/active FTP.
Fix: Set credentials and try passive mode (default).
aria2c --ftp-user=user --ftp-passwd=pass ftp://host/file
aria2c --ftp-pasv=true ftp://host/file # passive (default)
Expected: The FTP session logs in and transfers the file.
“Could not parse Metalink document” (exit code 20)
Symptom: A .meta4/.metalink download fails.
Cause: Malformed XML, or the URL returned an HTML error page instead of the Metalink.
Fix: Download the Metalink first and open it, and verify the URL returns the XML.
aria2c https://example.com/file.meta4 # download the metalink itself
aria2c file.meta4 # then use the local file
Expected: aria2 parses the Metalink and downloads its files.
aria2 downloads an HTML page instead of the file
Symptom: You get a small .html file or an “Access denied” page.
Cause: The link needs a login, a token, or a confirmation page.
Fix: Use the real file URL (or cookies from your browser).
aria2c --load-cookies cookies.txt URL
Expected: The response is the actual binary/file content.
BitTorrent: 0 peers / 0 KB/s
Symptom: A torrent starts but never finds peers.
Cause: Dead trackers, no DHT/LPD, and no inbound port.
Fix: Add fresh trackers, enable DHT/LPD, forward a port.
aria2c --enable-dht=true --bt-enable-lpd=true \
--bt-tracker="udp://tracker.opentrackr.org:1337/announce" \
--listen-port=6888 --dht-listen-port=6888 mytorrent.torrent
Expected: Peers connect and speed rises above 0.
Peers connect but I'm never “connectable”
Symptom: Downloads work but slowly; peers don't connect to you.
Cause: No inbound port (no forward, or CGNAT/VPN).
Fix: Forward one TCP+UDP port and set it in aria2; use a VPN with port forwarding if behind CGNAT.
aria2c --listen-port=6888 --dht-listen-port=6888 \
--bt-external-ip=YOUR_PUBLIC_IP mytorrent.torrent
Expected: The client becomes connectable and speeds improve.
“No registered tracker” / trackers not working
Symptom: The torrent lists trackers but none respond.
Cause: Trackers are offline, or UDP is blocked on your network.
Fix: Replace with fresh trackers and add HTTP(S) ones as fallback. See the tracker list.
aria2c --bt-tracker="udp://...,https://..." mytorrent.torrent
Expected: At least one tracker announces successfully and peers appear.
Magnet link fails or “command not found”
Symptom: Pasting a magnet URI breaks the command.
Cause: & and ? in the URI are interpreted by the shell.
Fix: Always wrap magnet links in double quotes.
aria2c "magnet:?xt=urn:btih:..."
Expected: aria2 fetches the metadata and starts the torrent.
Magnet: stuck on “fetching metadata”
Symptom: A magnet never progresses to actual downloading.
Cause: No peers/DHT source to fetch the torrent metadata from (dead swarm).
Fix: Add trackers so metadata can be fetched, or use the .torrent file directly.
aria2c --bt-tracker="udp://tracker.opentrackr.org:1337/announce" \
--enable-dht=true --bt-save-metadata=true "magnet:?xt=urn:btih:..."
Expected: Metadata arrives, a .torrent is saved, and the download begins.
Private tracker (PT) rejects or bans me / poor ratio
Symptom: A private-tracker torrent won't connect, or your account ratio suffers.
Cause: Private rules require the site tracker only, no DHT/PEX, and seeding.
Fix: Disable DHT/PEX and seed to the required ratio.
aria2c --enable-dht=false --enable-peer-exchange=false \
--bt-enable-lpd=false --seed-ratio=1.0 --seed-time=0 mytorrent.torrent
Expected: The private tracker accepts the client and seeding continues.
Seeding never stops
Symptom: The task stays active forever after 100%.
Cause: seed-ratio=0 (seed forever) or a high ratio target.
Fix: Set a ratio or time limit.
aria2c --seed-ratio=1.0 mytorrent.torrent # stop at ratio 1.0
aria2c --seed-time=0 mytorrent.torrent # stop right after finishing
Expected: Seeding stops when the condition is met.
“.torrent file corrupted”, “bencoded file” or “Magnet URI was bad” (exit 25/26/27)
Symptom: aria2 refuses to open a torrent or magnet.
Cause: A truncated/corrupt .torrent, or a malformed magnet URI.
Fix: Re-download the .torrent from the source, or copy the complete magnet string. Inspect with -S.
aria2c -S mytorrent.torrent # print file listing; fails if corrupt
Expected: aria2 lists the torrent contents and completes the download.
BitTorrent is much slower than qBittorrent/Transmission
Symptom: The same torrent is markedly slower in aria2.
Cause: Conservative defaults (peers, peer speed reward, upload) and no port forwarding.
Fix: Tune the swarm and forward a port (see the speed guide).
aria2c --bt-max-peers=128 --bt-request-peer-speed-limit=50K \
--enable-dht=true --bt-enable-lpd=true --listen-port=6888 mytorrent.torrent
Expected: Throughput approaches other clients.
WebUI / AriaNg says “Disconnected”
Symptom: The dashboard never connects to the daemon.
Cause: aria2 isn't running with RPC, wrong host/port, or the secret doesn't match.
Fix: Start RPC with a token and enter the same values in the WebUI.
aria2c --enable-rpc --rpc-secret=YOUR_SECRET --rpc-listen-all=true --daemon=true
# verify: curl http://127.0.0.1:6800/jsonrpc
Expected: The WebUI shows “Connected”.
“Failed to bind socket” / port 6800 already in use
Symptom: aria2 won't start with RPC enabled.
Cause: Another aria2 instance or app owns port 6800.
Fix: Stop the other process or use a different RPC port.
aria2c --rpc-listen-port=6801 --enable-rpc
Expected: aria2 starts and the RPC answers on the new port.
RPC error “unauthorized” / secret mismatch
Symptom: The client connects but every call returns an error.
Cause: The rpc-secret in the client doesn't match the daemon.
Fix: Use the exact same token in the WebUI/AriaNg and the daemon.
aria2c --enable-rpc --rpc-secret="My Token 123" --daemon=true
# In the WebUI, enter exactly: My Token 123
Expected: Calls succeed and downloads are listed.
“Mixed content” blocked on an HTTPS page
Symptom: The browser console blocks calls from an HTTPS page to your RPC.
Cause: An HTTPS page cannot call a plain http:///ws:// endpoint.
Fix: Serve the RPC over HTTPS/WSS through a reverse proxy (or use a VPN), and use that URL.
# Nginx: proxy /jsonrpc with Upgrade/Connection headers to enable WSS
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
Expected: The HTTPS WebUI connects without a mixed-content block.
CORS error calling the RPC from a web page
Symptom: Console shows a CORS policy error.
Cause: The daemon doesn't allow the page's origin.
Fix: Enable rpc-allow-origin-all=true (only when the port is not public).
aria2c --enable-rpc --rpc-allow-origin-all=true --rpc-secret=YOUR_SECRET --daemon=true
Expected: The browser can call the RPC endpoint.
RPC stops when I close the terminal
Symptom: Closing the shell kills aria2 and the WebUI disconnects.
Cause: aria2 was started in the foreground (not daemonized).
Fix: Run as a daemon, or as a service.
aria2c --enable-rpc --daemon=true
# or long-lived in a terminal:
nohup aria2c --enable-rpc --rpc-secret=SECRET >/dev/null 2>&1 &
Expected: aria2 keeps running after the shell exits.
Can't reach RPC from another machine
Symptom: localhost works, but the LAN IP does not.
Cause: The daemon binds only to localhost, or a firewall blocks the port.
Fix: Listen on all interfaces and allow the port through the firewall (keep it on a trusted network).
aria2c --enable-rpc --rpc-listen-all=true --rpc-secret=SECRET --daemon=true
Expected: The remote client reaches the RPC at the LAN IP.
“Could not parse JSON-RPC request” (exit code 30)
Symptom: An integration calling aria2 fails to parse its own request.
Cause: Malformed JSON-RPC body, or a wrong method/params shape.
Fix: Validate the request body; remember params must include the token first.
Expected: The RPC accepts the request and returns a result.
“Network problem has occurred” (errorCode=1)
Symptom: Every download fails with Exception: [AbstractCommand.cc:...] errorCode=1.
Cause: Often a system proxy that is set but not running, a firewall/antivirus, or IPv6 problems.
Fix: Remove the dead proxy, or disable IPv6; check the hosts file.
aria2c --disable-ipv6=true URL
# also verify no stale proxy: aria2c --all-proxy="" URL
Expected: aria2 connects and downloads normally.
“Name resolution failed” (exit code 19)
Symptom: aria2 can't resolve the hostname.
Cause: Broken DNS, an unreachable resolver, or a bad hosts entry.
Fix: Test DNS, and try a specific resolver or disable async DNS.
nslookup example.com
aria2c --async-dns=false URL
aria2c --async-dns-server=1.1.1.1 URL
Expected: The hostname resolves and the connection is made.
Proxy connection refused or proxy authentication failed
Symptom: Downloads fail because the proxy is wrong, down, or rejects auth.
Cause: Proxy set globally but not running, or wrong credentials.
Fix: Provide the correct proxy with credentials, or clear it. aria2 only speaks to HTTP proxies — a socks5:// URL fails with “unrecognized proxy format”.
aria2c --all-proxy="http://user:pass@127.0.0.1:8080" URL
# aria2 has no SOCKS support: point it at an HTTP proxy or an HTTP-to-SOCKS bridge
aria2c --all-proxy="" URL # disable proxy
Expected: Traffic goes through the proxy and the download proceeds.
Downloads fail only on some hosts (IPv6 issue)
Symptom: Specific sites fail while others work, often with a network error.
Cause: Broken IPv6 connectivity; aria2 prefers an IPv6 route that black-holes.
Fix: Disable IPv6 in aria2.
aria2c --disable-ipv6=true URL
Expected: aria2 uses IPv4 and the download succeeds.
Hosts file or firewall silently blocks the server
Symptom: The domain resolves but connects to nowhere (or 127.0.0.1).
Cause: A debloat/telemetry blocker or antivirus added a null route.
Fix: Check the hosts file and firewall, and remove the blocking entry.
# Windows: C:\Windows\System32\drivers\etc\hosts
# Linux/macOS: /etc/hosts (look for the domain)
Expected: The domain connects to its real IP and downloads.
“Not enough disk space” (exit code 9)
Symptom: The download aborts with a disk-space error.
Cause: The target drive is full, or preallocation needs more than is free.
Fix: Free space, choose another --dir, or lower preallocation.
aria2c -d /path/with/space URL
aria2c --file-allocation=none URL
Expected: The file is written without a space error.
Permission denied / “could not create new file” (exit code 16)
Symptom: aria2 can't write to the target folder.
Cause: The user (or container) lacks write permission.
Fix: Write to a folder you own, or fix permissions/ownership.
aria2c -d ~/Downloads URL
ls -ld ~/Downloads
# Docker: set user: "1000:1000" or chown the mounted folder
Expected: The file is created and written.
“File I/O error”, “could not open existing file”, “could not create directory” (exit 15/17/18)
Symptom: aria2 fails while creating or writing the file/directory.
Cause: Bad path, invalid characters, a read-only/removed drive, or a failing disk.
Fix: Use a short, valid, writable path; check the drive.
aria2c -d /mnt/data/downloads --out=file.iso URL
Expected: Directories and files are created without I/O errors.
Download fails on a USB/exFAT/FAT32 drive (files over 4 GB)
Symptom: Large files fail or corrupt on FAT32/exFAT sticks.
Cause: FAT32 has a 4 GB per-file limit; some exFAT drivers are flaky with huge sparse files.
Fix: Use NTFS/ext4, or download to an internal disk first.
Expected: Large files write correctly on a suitable filesystem.
Downloads to an SMB/NFS share stall or corrupt
Symptom: Writing to a network share is slow, hangs, or fails.
Cause: falloc/prealloc and sparse files are poorly supported over network shares.
Fix: Use none allocation on network shares, and a small disk cache.
aria2c --file-allocation=none --disk-cache=16M -d /mnt/nas/downloads URL
Expected: Writes complete reliably on the share.
“Piece length was different from one in .aria2 control file” (exit code 10)
Symptom: Resume fails with a piece-length mismatch.
Cause: The .aria2 file belongs to a different file (or a different server config).
Fix: Delete the mismatched control file and restart, or allow the change.
# safest: remove the stale control file, then re-download
aria2c --allow-piece-length-change=true URL
Expected: The download proceeds; the control file matches.
“File already existed” (exit 13) / “renaming failed” (exit 14)
Symptom: aria2 refuses to write because a file with that name exists.
Cause: Overwrite protection is on, or auto-rename hit an invalid name.
Fix: Allow overwrite or auto-rename.
aria2c --allow-overwrite=true URL
aria2c --auto-file-renaming=true URL
Expected: aria2 overwrites or renames and continues.
PC freezes / 100% disk usage while downloading
Symptom: The whole system lags during large downloads.
Cause: Preallocation and many small writes on an HDD or slow disk.
Fix: Use falloc (or trunc), raise the disk cache, and reduce connections.
aria2c --file-allocation=falloc --disk-cache=64M -x 8 -s 8 URL
Expected: Disk usage is smoother and the system stays responsive.
Windows: “path is too long” / cannot create file
Symptom: Long torrent/file names fail on Windows.
Cause: The classic 260-character MAX_PATH limit.
Fix: Shorten --dir, or enable long paths in Windows.
aria2c -d C:\dl URL
Expected: The file is created within the path limit.
Resume restarts from 0%
Symptom: Re-running the download begins from the start.
Cause: Missing -c, a renamed/moved file, or a missing control file.
Fix: Keep file.ext + file.ext.aria2 together and run with -c.
aria2c -c -x 16 -s 16 URL
Expected: aria2 continues from the existing pieces.
The .aria2 file is not deleted after 100%
Symptom: file.ext.aria2 remains after completion.
Cause: BitTorrent seeding is still active, or the integrity check didn't pass.
Fix: Stop seeding/remove the task, or verify the file.
aria2c -c --check-integrity=true URL
Expected: Once the file is sealed, aria2 removes the control file. See the .aria2 guide.
“The file is corrupt” when opening a partial download
Symptom: A media player or archiver rejects the incomplete file.
Cause: The file is simply not finished (the .aria2 file is still present).
Fix: Resume the download; do not delete the control file.
Expected: The file is valid once the download completes.
Downloads disappear after a restart
Symptom: Restarting aria2 loses the queue/progress.
Cause: No session persistence configured.
Fix: Configure a session file and interval.
save-session=/config/aria2.session
input-file=/config/aria2.session
save-session-interval=60
continue=true
Expected: aria2 reloads the queue and resumes on start.
aria2 won’t start: “Failed to open the file …aria2.session, cause: File not found”
Symptom: aria2 exits immediately on start with errorCode=1 Failed to open the file …/aria2.session; a Docker container keeps restarting.
Cause: input-file points at a session file that does not exist yet. aria2 only creates it on save-session, but refuses to start without it. Note that aria2 expands ${HOME} in this path but not ~.
Fix: Create the empty file once, and use an absolute path or ${HOME} in aria2.conf.
mkdir -p ~/.aria2 && touch ~/.aria2/aria2.session # Linux/macOS
type nul > "%USERPROFILE%\.aria2\aria2.session" # Windows (cmd)
# Docker: touch the file inside the mounted /config folder
Expected: aria2 starts with an empty queue and from then on saves and restores it automatically.
“Downloading same file/info hash at that moment” (exit 11/12)
Symptom: aria2 refuses to add a duplicate task.
Cause: The same URI or torrent is already in the queue.
Fix: Manage the existing task (or change the output name).
Expected: Only one instance of the task exists.
Downloads are much slower than my connection
Symptom: speeds far below your bandwidth.
Cause: aria2's HTTP default is a single connection per server.
Fix: Increase connections and splits.
aria2c -x 16 -s 16 -k 1M URL
# HDD: add --file-allocation=falloc
Expected: Speed rises toward your line rate. See the speed guide.
Speed is capped at a fixed number
Symptom: Speed sits at a round figure (e.g. exactly 5 MB/s).
Cause: A limit option is set (0 = unlimited).
Fix: Clear the download/upload limits.
max-overall-download-limit=0
max-download-limit=0
max-overall-upload-limit=0
Expected: Speed is limited only by the network/disk.
aria2 uses too much memory or CPU
Symptom: High RAM or CPU while downloading.
Cause: Very high disk-cache, hundreds of connections, or huge peer counts.
Fix: Lower the cache and connection/peer limits.
aria2c --disk-cache=32M -x 8 -s 8 --max-concurrent-downloads=3 -j 3 URL
Expected: Resource use drops while speeds stay acceptable.
“Download aborted because speed was too slow” (exit code 5)
Symptom: aria2 gives up on a slow source.
Cause: lowest-speed-limit is too high for this server.
Fix: Lower or remove the limit.
aria2c --lowest-speed-limit=0 URL
# or a gentle floor: --lowest-speed-limit=1K
Expected: The download continues despite the slow source.
“Bad or unrecognized option” (exit code 28)
Symptom: aria2 fails to start with an option error.
Cause: A typo, a misspelled key, or an older build lacking the option.
Fix: Check the key against the options reference and update aria2.
Expected: aria2 parses the configuration and starts.
My aria2.conf is ignored
Symptom: Settings in the file have no effect.
Cause: The file is in the wrong location, has a wrong name, or command-line flags override it.
Fix: Use the correct path, and remember command-line options take precedence.
# Linux/macOS: ~/.aria2/aria2.conf
# Windows: %USERPROFILE%\.aria2\aria2.conf
aria2c --conf-path=/path/to/aria2.conf
Expected: The configured options take effect at startup.
Windows: options in --downloader-args are ignored
Symptom: aria2 flags passed through yt-dlp don't apply.
Cause: Shell quoting split the aria2c: value.
Fix: Wrap the whole value in double quotes; don't mix quote types.
yt-dlp --downloader aria2c --downloader-args "aria2c:-x 16 -s 16 -k 1M" URL
Expected: The flags reach aria2 and speed increases.
Is it dangerous to expose port 6800?
Symptom: The RPC port is reachable from the internet.
Cause: rpc-listen-all=true plus a router port-forward or public IP.
Fix: Never expose 6800 publicly. Keep it on localhost/LAN and use a VPN or an authenticated HTTPS reverse proxy.
# Keep local:
rpc-listen-all=false
# Always set a strong token when enabled:
rpc-secret=long-random-string
Expected: Only trusted networks can reach the RPC.
rpc-allow-origin-all lets any website control my daemon
Symptom: You enabled CORS for the WebUI and worry about exposure.
Cause: With CORS open, any page you visit can call the RPC if it can reach the port.
Fix: Keep the port private, use a strong secret, and prefer a local page/proxy over exposing the port.
Expected: The WebUI works while no untrusted site can reach the RPC.
Safety: torrents, Metalinks and .aria2 files from unknown sources
Symptom: You're about to download from an untrusted source.
Cause: Torrents/Metalinks can point to malicious content; a foreign .aria2 file shouldn't be trusted.
Fix: Prefer official sources, verify checksums/signatures, and never reuse a .aria2 file for a different file.
aria2c --check-integrity=true --checksum=sha-256=HEXDIGEST URL
Expected: The file's hash matches the published digest.