aria2c: Befehl nicht gefunden / „aria2c wird nicht erkannt“
Symptom: Die Shell meldet aria2c: command not found, 'aria2c' is not recognized, oder yt-dlp meldet „aria2c is not installed. please install it first.“
Ursache: aria2 ist nicht installiert, oder sein Ordner liegt nicht im PATH.
Lösung: Installieren Sie es und öffnen Sie das Terminal neu, damit der PATH aktualisiert wird.
sudo apt install aria2 # Debian/Ubuntu
brew install aria2 # macOS
winget install aria2.aria2 # Windows (oder scoop/choco)
aria2c --version
Erwartet: aria2c --version gibt eine Version wie 1.37.0 aus.
Windows: aria2 installiert, aber das Terminal findet es nicht
Symptom: Sie haben aria2 entpackt, aber jedes neue Terminal kennt den Befehl nicht.
Ursache: Der Ordner mit aria2c.exe wurde nie zur Path-Variable hinzugefügt.
Lösung: Ordner zu Path hinzufügen und ein neues Terminal öffnen (bestehende behalten die alte Umgebung).
# Beispielordner: C:\aria2
setx PATH "%PATH%;C:\aria2"
Erwartet: Ein frisch geöffnetes CMD/PowerShell findet aria2c.
error while loading shared libraries: libxml2.so.2 / libcares.so.2
Symptom: aria2c bricht sofort mit einer fehlenden Shared Library ab.
Ursache: Benötigte Bibliotheken fehlen, oder die Binärdatei passt nicht zum System.
Lösung: Installieren Sie die Abhängigkeiten Ihrer Distribution.
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 # installiert mit Abhängigkeiten neu
Erwartet: aria2c --version läuft ohne Bibliotheksfehler.
Windows: „The code execution cannot proceed because zlib1.dll/libssh2.dll was not found“
Symptom: Beim Start von aria2c.exe erscheint ein DLL-Fehler.
Ursache: aria2c.exe wurde aus dem ZIP-Ordner entfernt, weg von den mitgelieferten DLLs.
Lösung: Den gesamten entpackten Ordner zusammen lassen und diesen Ordner zu Path hinzufügen.
Erwartet: aria2c startet und gibt die Version aus.
macOS: „cannot be opened because the developer cannot be verified“
Symptom: macOS (Gatekeeper) verweigert den Start der heruntergeladenen Binärdatei.
Ursache: Die Datei ist in Quarantäne, weil sie nicht signiert/notarisiert ist.
Lösung: Homebrew bevorzugen oder das Quarantäne-Attribut entfernen.
brew install aria2
# oder manuell:
xattr -d com.apple.quarantine ./aria2c
Erwartet: Gatekeeper lässt die Binärdatei zu.
Windows Defender / SmartScreen blockiert aria2c.exe
Symptom: „Windows hat Ihren PC geschützt“ oder die Datei wird kurz nach dem Download gelöscht.
Ursache: Unsigned-CLI-Binärdateien werden manchmal heuristisch gemeldet (Falsch-positiv).
Lösung: Nur von den offiziellen GitHub-Releases laden, Prüfsumme verifizieren und die Datei zulassen; oder via winget/scoop/choco installieren.
winget install aria2.aria2
# Archiv gegen die Release-Prüfsummen verifizieren
Erwartet: aria2c läuft und wird nicht entfernt.
Docker: Container beendet sich sofort, oder der RPC-Port ist nicht erreichbar
Symptom: Der Container startet in einer Schleife neu, oder Port 6800 antwortet nicht.
Ursache: Falscher Entrypoint/Befehl, fehlende Konfig, oder RPC nur an localhost im Container gebunden.
Lösung: Logs prüfen; --enable-rpc, rpc-listen-all=true und veröffentlichten Port sicherstellen.
docker compose logs -f aria2
docker compose ps
# Dienst muss mappen: ports: ["6800:6800"]
Erwartet: curl http://localhost:6800/jsonrpc liefert eine JSON-RPC-Antwort.
aria2c: unable to verify certificate (SSL-Fehler)
Symptom: HTTPS-Downloads schlagen mit einem Zertifikatsfehler fehl.
Ursache: Veraltete Root-CA-Zertifikate oder ein selbstsigniertes/internes Zertifikat.
Lösung: CA-Bundle aktualisieren oder aria2 darauf zeigen; für interne Seiten die CA ergänzen.
sudo apt install ca-certificates # Debian/Ubuntu
aria2c --ca-certificate=/etc/ssl/certs/ca-certificates.crt URL
# Nur bei vertrauenswürdiger Quelle und ohne CA:
# aria2c --check-certificate=false URL
Erwartet: Der Download startet ohne Zertifikatswarnung.
SSL/TLS-Handshake-Fehler / „openssl error:00000000“
Symptom: Die Verbindung bricht während des TLS-Handshakes ab; keine Daten.
Ursache: Veralteter TLS-Stack, ein abfangender Proxy/Antivirus oder eine nicht unterstützte Protokollversion.
Lösung: aria2 und OS aktualisieren; ohne Proxy testen; anderes Netzwerk probieren.
Erwartet: Der Handshake gelingt und der Download läuft.
--ca-certificate scheint ignoriert zu werden (Windows/macOS)
Symptom: --ca-certificate zeigt keine Wirkung.
Ursache: Die Windows- (WinTLS) und macOS- (AppleTLS) Backends unterstützen das nicht; sie nutzen den OS-Trust-Store.
Lösung: Zertifikat in den OS-Trust-Store importieren.
Erwartet: HTTPS gelingt mit dem OS-vertrauten Zertifikat.
HTTP 403 Forbidden
Symptom: Der Server liefert 403 und der Download stoppt.
Ursache: Die Datei verlangt Session-Cookies, einen Referer oder einen Browser-User-Agent (Hotlink-Schutz).
Lösung: Cookies und Header übergeben.
aria2c --header="Cookie: session=..." --referer="https://example.com/page" URL
aria2c --load-cookies cookies.txt URL
aria2c --user-agent="Mozilla/5.0" URL
Erwartet: Der Server liefert 200 und die Übertragung beginnt.
HTTP 404 Not Found (Exit-Code 3)
Symptom: aria2 endet mit Code 3 und wiederholt „resource not found“.
Ursache: Die URL ist falsch, abgelaufen, oder die Datei wurde entfernt (häufig bei signierten Links).
Lösung: Neue URL holen und ein Retry-Limit setzen.
aria2c --max-tries=3 --max-file-not-found=1 URL
Erwartet: aria2 stoppt schnell statt zu schleifen, oder gelingt mit der neuen URL.
HTTP 429 Too Many Requests
Symptom: Der Server limitiert Sie nach einem Anfrage-Burst.
Ursache: Zu viele parallele Verbindungen/Dateien in kurzer Zeit.
Lösung: Verbindungen/Parallelität senken und Pausen ergänzen.
aria2c -x 4 -s 4 --max-concurrent-downloads=2 --retry-wait=10 URL
Erwartet: Die Anfragen bleiben unter dem Limit und Downloads laufen.
HTTP 503 Service Unavailable
Symptom: Der Server ist vorübergehend überlastet oder in Wartung.
Ursache: Kurzzeitige serverseitige Last oder Drosselung.
Lösung: Warten und erneut versuchen; --retry-wait wiederholt 503 automatisch.
aria2c --retry-wait=15 --max-tries=10 URL
Erwartet: aria2 wartet und wiederholt, bis der Server sich erholt.
HTTP 401 Unauthorized / „HTTP authorization failed“ (Exit-Code 24)
Symptom: aria2 meldet einen Autorisierungsfehler.
Ursache: Falsche oder fehlende Zugangsdaten (auch Basic/Bearer).
Lösung: Zugangsdaten via User/Pass oder Authorization-Header übergeben.
aria2c --http-user=user --http-passwd=pass URL
# oder in der URI: https://user:pass@host/file
aria2c --header="Authorization: Bearer TOKEN" URL
Erwartet: Der Server authentifiziert und sendet Daten.
Too many redirects (Exit-Code 23)
Symptom: aria2 bricht mit „too many redirects“ ab.
Ursache: Eine Weiterleitungsschleife oder ein CDN, das Cookies/Header verlangt.
Lösung: Die endgültige URL direkt verwenden oder Cookies und Referer liefern.
Erwartet: aria2 erreicht die finale 200-Antwort.
„Remote server did not support resume“ (Exit-Code 8)
Symptom: Sie nutzen -c, aber aria2 setzt nicht fort.
Ursache: Der Server ignoriert Byte-Range-Anfragen, oder die Datei änderte sich (Größe/ETag).
Lösung: Ohne -c neu starten oder einen range-fähigen Mirror nutzen.
aria2c URL # frischer Download (ohne -c)
aria2c -x 16 -s 16 URL # von einem range-fähigen Mirror
Erwartet: Ein vollständiger Download gelingt.
Timeout (Exit-Code 2)
Symptom: aria2 bricht mit einem Timeout ab.
Ursache: Ein langsamer/instabiler Server oder ein zu kurzes Timeout.
Lösung: Timeouts und Wiederholungen erhöhen; hängende Verbindungen verwerfen.
aria2c --timeout=60 --connect-timeout=30 --max-tries=5 --retry-wait=5 -c URL
Erwartet: aria2 wiederholt und setzt fort statt abzubrechen.
FTP: Login fehlgeschlagen / „FTP command failed“ (Exit-Code 21)
Symptom: FTP-Transfers scheitern mit Auth- oder Kommandofehler.
Ursache: Falsche Zugangsdaten oder eine Firewall blockiert passives/aktives FTP.
Lösung: Zugangsdaten setzen und passiven Modus (Standard) versuchen.
aria2c --ftp-user=user --ftp-passwd=pass ftp://host/file
aria2c --ftp-pasv=true ftp://host/file # passiv (Standard)
Erwartet: Die FTP-Sitzung meldet sich an und überträgt die Datei.
„Could not parse Metalink document“ (Exit-Code 20)
Symptom: Ein .meta4/.metalink-Download scheitert.
Ursache: Fehlerhaftes XML, oder die URL lieferte eine HTML-Fehlerseite statt des Metalink.
Lösung: Zuerst das Metalink herunterladen und lokal öffnen; prüfen, dass die URL das XML liefert.
aria2c https://example.com/file.meta4 # Metalink selbst laden
aria2c file.meta4 # dann die lokale Datei nutzen
Erwartet: aria2 parst das Metalink und lädt die Dateien.
aria2 lädt eine HTML-Seite statt der Datei
Symptom: Sie erhalten eine kleine .html-Datei oder eine „Access denied“-Seite.
Ursache: Der Link benötigt Login, Token oder eine Bestätigungsseite.
Lösung: Die echte Datei-URL verwenden (oder Cookies aus dem Browser).
aria2c --load-cookies cookies.txt URL
Erwartet: Die Antwort ist der echte Binär-/Dateiinhalt.
BitTorrent: 0 Peers / 0 KB/s
Symptom: Ein Torrent startet, findet aber nie Peers.
Ursache: Tote Tracker, kein DHT/LPD und kein eingehender Port.
Lösung: Frische Tracker ergänzen, DHT/LPD aktivieren, Port weiterleiten.
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
Erwartet: Peers verbinden sich und die Geschwindigkeit steigt über 0.
Peers verbinden, aber ich bin nie „connectable“
Symptom: Downloads laufen langsam; Peers verbinden nicht zu Ihnen.
Ursache: Kein eingehender Port (kein Forward, oder CGNAT/VPN).
Lösung: Einen TCP+UDP-Port weiterleiten und in aria2 setzen; hinter CGNAT ein VPN mit Port-Forwarding nutzen.
aria2c --listen-port=6888 --dht-listen-port=6888 \
--bt-external-ip=DEINE_PUBLIC_IP mytorrent.torrent
Erwartet: Der Client wird connectable und schneller.
„No registered tracker“ / Tracker funktionieren nicht
Symptom: Der Torrent listet Tracker, aber keiner antwortet.
Ursache: Tracker sind offline, oder UDP ist im Netz blockiert.
Lösung: Durch frische Tracker ersetzen und HTTP(S) als Fallback ergänzen. Siehe Tracker-Liste.
aria2c --bt-tracker="udp://...,https://..." mytorrent.torrent
Erwartet: Mindestens ein Tracker annonciert erfolgreich und Peers erscheinen.
Magnet-Link schlägt fehl oder „Befehl nicht gefunden“
Symptom: Ein eingefügter Magnet-URI zerbricht den Befehl.
Ursache: & und ? in der URI werden von der Shell interpretiert.
Lösung: Magnet-Links immer in doppelte Anführungszeichen setzen.
aria2c "magnet:?xt=urn:btih:..."
Erwartet: aria2 lädt die Metadaten und startet den Torrent.
Magnet: hängt bei „fetching metadata“
Symptom: Ein Magnet kommt nie zum eigentlichen Download.
Ursache: Keine Peers/DHT-Quelle, um die Torrent-Metadaten zu holen (toter Swarm).
Lösung: Tracker ergänzen, damit Metadaten geladen werden können, oder die .torrent-Datei direkt nutzen.
aria2c --bt-tracker="udp://tracker.opentrackr.org:1337/announce" \
--enable-dht=true --bt-save-metadata=true "magnet:?xt=urn:btih:..."
Erwartet: Metadaten kommen an, eine .torrent wird gespeichert, der Download startet.
Private Tracker (PT) lehnt ab / sperrt mich, schlechte Ratio
Symptom: Ein PT-Torrent verbindet nicht, oder die Ratio leidet.
Ursache: Private Regeln verlangen nur den Site-Tracker, kein DHT/PEX und Seeding.
Lösung: DHT/PEX deaktivieren und bis zur geforderten Ratio seeden.
aria2c --enable-dht=false --enable-peer-exchange=false \
--bt-enable-lpd=false --seed-ratio=1.0 --seed-time=0 mytorrent.torrent
Erwartet: Der private Tracker akzeptiert den Client und das Seeding läuft.
Seeding endet nie
Symptom: Die Aufgabe bleibt nach 100% dauerhaft aktiv.
Ursache: seed-ratio=0 (dauerhaft seeden) oder ein hohes Ratio-Ziel.
Lösung: Ratio- oder Zeitlimit setzen.
aria2c --seed-ratio=1.0 mytorrent.torrent # bei Ratio 1.0 stoppen
aria2c --seed-time=0 mytorrent.torrent # direkt nach Abschluss stoppen
Erwartet: Seeding stoppt, wenn die Bedingung erfüllt ist.
„.torrent file corrupted“, „bencoded file“ oder „Magnet URI was bad“ (Exit 25/26/27)
Symptom: aria2 öffnet Torrent oder Magnet nicht.
Ursache: Eine abgeschnittene/kaputte .torrent oder ein fehlerhafter Magnet-URI.
Lösung: Die .torrent neu laden oder den vollständigen Magnet kopieren. Mit -S prüfen.
aria2c -S mytorrent.torrent # Dateiliste ausgeben; scheitert bei Kaputtheit
Erwartet: aria2 listet den Inhalt und lädt den Torrent.
BitTorrent ist viel langsamer als qBittorrent/Transmission
Symptom: Derselbe Torrent ist in aria2 deutlich langsamer.
Ursache: Konservative Standards (Peers, Peer-Speed-Belohnung, Upload) und kein Port-Forwarding.
Lösung: Swarm-Optionen tunen und Port weiterleiten (siehe Geschwindigkeits-Leitfaden).
aria2c --bt-max-peers=128 --bt-request-peer-speed-limit=50K \
--enable-dht=true --bt-enable-lpd=true --listen-port=6888 mytorrent.torrent
Erwartet: Der Durchsatz nähert sich anderen Clients an.
WebUI / AriaNg meldet „Disconnected“
Symptom: Das Dashboard verbindet nie zum Daemon.
Ursache: aria2 läuft nicht mit RPC, falscher Host/Port, oder das Secret stimmt nicht.
Lösung: RPC mit Token starten und dieselben Werte im WebUI eintragen.
aria2c --enable-rpc --rpc-secret=YOUR_SECRET --rpc-listen-all=true --daemon=true
# prüfen: curl http://127.0.0.1:6800/jsonrpc
Erwartet: Das WebUI zeigt „Connected“.
„Failed to bind socket“ / Port 6800 bereits belegt
Symptom: aria2 startet nicht mit aktiviertem RPC.
Ursache: Eine andere aria2-Instanz oder App belegt Port 6800.
Lösung: Anderen Prozess stoppen oder einen anderen RPC-Port nutzen.
aria2c --rpc-listen-port=6801 --enable-rpc
Erwartet: aria2 startet und RPC antwortet auf dem neuen Port.
RPC-Fehler „unauthorized“ / Secret stimmt nicht
Symptom: Der Client verbindet, aber jeder Aufruf liefert einen Fehler.
Ursache: Das rpc-secret im Client passt nicht zum Daemon.
Lösung: Exakt denselben Token in WebUI/AriaNg und Daemon verwenden.
aria2c --enable-rpc --rpc-secret="Mein Token 123" --daemon=true
# Im WebUI exakt eingeben: Mein Token 123
Erwartet: Aufrufe gelingen und Downloads werden gelistet.
„Mixed content“ auf einer HTTPS-Seite blockiert
Symptom: Die Browser-Konsole blockiert Aufrufe von einer HTTPS-Seite zu Ihrem RPC.
Ursache: Eine HTTPS-Seite kann keinen einfachen http:///ws://-Endpunkt aufrufen.
Lösung: RPC über HTTPS/WSS via Reverse-Proxy (oder VPN) bereitstellen und diese URL nutzen.
# Nginx: /jsonrpc mit Upgrade/Connection-Headern für WSS proxien
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
Erwartet: Das HTTPS-WebUI verbindet ohne Mixed-Content-Block.
CORS-Fehler beim RPC-Aufruf aus einer Webseite
Symptom: Die Konsole zeigt einen CORS-Policy-Fehler.
Ursache: Der Daemon erlaubt den Ursprung der Seite nicht.
Lösung: rpc-allow-origin-all=true aktivieren (nur wenn der Port nicht öffentlich ist).
aria2c --enable-rpc --rpc-allow-origin-all=true --rpc-secret=YOUR_SECRET --daemon=true
Erwartet: Der Browser kann den RPC-Endpunkt aufrufen.
RPC stoppt, wenn ich das Terminal schließe
Symptom: Das Schließen der Shell beendet aria2 und das WebUI trennt sich.
Ursache: aria2 wurde im Vordergrund gestartet (nicht als Daemon).
Lösung: Als Daemon oder Dienst ausführen.
aria2c --enable-rpc --daemon=true
# oder langlebig im Terminal:
nohup aria2c --enable-rpc --rpc-secret=SECRET >/dev/null 2>&1 &
Erwartet: aria2 läuft nach dem Shell-Ende weiter.
RPC von einem anderen Rechner nicht erreichbar
Symptom: localhost funktioniert, die LAN-IP nicht.
Ursache: Der Daemon bindet nur an localhost, oder eine Firewall blockiert den Port.
Lösung: An allen Interfaces lauschen und den Port in der Firewall freigeben (nur in vertrauenswürdigen Netzen).
aria2c --enable-rpc --rpc-listen-all=true --rpc-secret=SECRET --daemon=true
Erwartet: Der entfernte Client erreicht den RPC unter der LAN-IP.
„Could not parse JSON-RPC request“ (Exit-Code 30)
Symptom: Eine Integration, die aria2 aufruft, kann ihre eigene Anfrage nicht parsen.
Ursache: Fehlerhafter JSON-RPC-Body oder falsche Methode/Params.
Lösung: Den Body validieren; params muss zuerst den Token enthalten.
Erwartet: Der RPC akzeptiert die Anfrage und liefert ein Ergebnis.
„Network problem has occurred“ (errorCode=1)
Symptom: Jeder Download scheitert mit Exception: [AbstractCommand.cc:...] errorCode=1.
Ursache: Oft ein gesetzter, aber nicht laufender System-Proxy, Firewall/Antivirus oder IPv6-Probleme.
Lösung: Den toten Proxy entfernen oder IPv6 deaktivieren; hosts-Datei prüfen.
aria2c --disable-ipv6=true URL
# auch prüfen: aria2c --all-proxy="" URL
Erwartet: aria2 verbindet und lädt normal.
„Name resolution failed“ (Exit-Code 19)
Symptom: aria2 kann den Hostnamen nicht auflösen.
Ursache: Defektes DNS, unerreichbarer Resolver oder ein falscher hosts-Eintrag.
Lösung: DNS testen und einen bestimmten Resolver setzen oder async DNS deaktivieren.
nslookup example.com
aria2c --async-dns=false URL
aria2c --async-dns-server=1.1.1.1 URL
Erwartet: Der Hostname wird aufgelöst und die Verbindung hergestellt.
Proxy-Verbindung verweigert oder Proxy-Authentifizierung fehlgeschlagen
Symptom: Downloads scheitern, weil der Proxy falsch, aus oder die Auth abgelehnt wird.
Ursache: Global gesetzter Proxy läuft nicht, oder falsche Zugangsdaten.
Lösung: Korrekten Proxy mit Zugangsdaten angeben oder leeren. aria2 spricht nur mit HTTP-Proxys – eine socks5://-URL schlägt mit „unrecognized proxy format“ fehl.
aria2c --all-proxy="http://user:pass@127.0.0.1:8080" URL
# aria2 kann kein SOCKS: HTTP-Proxy oder HTTP-zu-SOCKS-Brücke verwenden
aria2c --all-proxy="" URL # Proxy deaktivieren
Erwartet: Der Verkehr läuft über den Proxy und der Download geht weiter.
Downloads scheitern nur bei manchen Hosts (IPv6-Problem)
Symptom: Bestimmte Seiten scheitern, andere funktionieren, oft mit Netzwerkfehler.
Ursache: Defekte IPv6-Konnektivität; aria2 bevorzugt eine IPv6-Route, die ins Leere führt.
Lösung: IPv6 in aria2 deaktivieren.
aria2c --disable-ipv6=true URL
Erwartet: aria2 nutzt IPv4 und der Download gelingt.
hosts-Datei oder Firewall blockiert den Server still
Symptom: Die Domain löst auf, verbindet aber ins Nichts (oder 127.0.0.1).
Ursache: Ein Debloat-/Telemetrie-Blocker oder Antivirus hat eine Nullroute gesetzt.
Lösung: hosts-Datei und Firewall prüfen und den Blockeintrag entfernen.
# Windows: C:\Windows\System32\drivers\etc\hosts
# Linux/macOS: /etc/hosts (nach der Domain suchen)
Erwartet: Die Domain verbindet zur echten IP und lädt.
„Not enough disk space“ (Exit-Code 9)
Symptom: Der Download bricht mit einem Speicherplatzfehler ab.
Ursache: Das Ziellaufwerk ist voll, oder die Vorreservierung braucht mehr als frei ist.
Lösung: Platz freigeben, anderes --dir wählen oder Vorreservierung senken.
aria2c -d /pfad/mit/platz URL
aria2c --file-allocation=none URL
Erwartet: Die Datei wird ohne Platzfehler geschrieben.
Zugriff verweigert / „could not create new file“ (Exit-Code 16)
Symptom: aria2 kann nicht in den Zielordner schreiben.
Ursache: Der Benutzer (oder Container) hat keine Schreibrechte.
Lösung: In einen eigenen Ordner schreiben oder Rechte/Eigentümer korrigieren.
aria2c -d ~/Downloads URL
ls -ld ~/Downloads
# Docker: user: "1000:1000" setzen oder gemounteten Ordner chownen
Erwartet: Die Datei wird erstellt und geschrieben.
„File I/O error“, „could not open existing file“, „could not create directory“ (Exit 15/17/18)
Symptom: aria2 scheitert beim Erstellen/Schreiben von Datei/Ordner.
Ursache: Falscher Pfad, ungültige Zeichen, ein schreibgeschütztes/entferntes Laufwerk oder eine defekte Platte.
Lösung: Kurzen, gültigen, beschreibbaren Pfad nutzen; Laufwerk prüfen.
aria2c -d /mnt/data/downloads --out=file.iso URL
Erwartet: Ordner und Dateien werden ohne I/O-Fehler erstellt.
Download scheitert auf USB/exFAT/FAT32 (Dateien über 4 GB)
Symptom: Große Dateien scheitern oder korrumpieren auf FAT32/exFAT-Sticks.
Ursache: FAT32 hat ein 4-GB-Limit pro Datei; manche exFAT-Treiber sind mit riesigen Dateien instabil.
Lösung: NTFS/ext4 verwenden oder zuerst auf eine interne Platte laden.
Erwartet: Große Dateien schreiben auf einem geeigneten Dateisystem korrekt.
Downloads auf eine SMB/NFS-Freigabe hängen oder korrumpieren
Symptom: Schreiben auf eine Netzwerkfreigabe ist langsam, hängt oder scheitert.
Ursache: falloc/prealloc und sparse Dateien sind über Netzwerkfreigaben schlecht unterstützt.
Lösung: none-Allocation auf Netzwerkfreigaben und kleiner Disk-Cache.
aria2c --file-allocation=none --disk-cache=16M -d /mnt/nas/downloads URL
Erwartet: Schreibvorgänge laufen zuverlässig auf der Freigabe.
„Piece length was different from one in .aria2 control file“ (Exit-Code 10)
Symptom: Fortsetzen scheitert an einer Piece-Length-Abweichung.
Ursache: Die .aria2-Datei gehört zu einer anderen Datei (oder Serverkonfig).
Lösung: Die falsche Kontrolldatei löschen und neu starten oder die Änderung zulassen.
# am sichersten: veraltete Kontrolldatei entfernen, dann neu laden
aria2c --allow-piece-length-change=true URL
Erwartet: Der Download läuft; die Kontrolldatei passt.
„File already existed“ (Exit 13) / „renaming failed“ (Exit 14)
Symptom: aria2 weigert sich zu schreiben, weil eine gleichnamige Datei existiert.
Ursache: Überschreibschutz aktiv, oder Auto-Rename traf einen ungültigen Namen.
Lösung: Überschreiben oder Auto-Rename erlauben.
aria2c --allow-overwrite=true URL
aria2c --auto-file-renaming=true URL
Erwartet: aria2 überschreibt oder benennt um und läuft weiter.
PC friert ein / 100% Datenträgerauslastung beim Download
Symptom: Das ganze System ruckelt bei großen Downloads.
Ursache: Vorreservierung und viele kleine Schreibvorgänge auf einer HDD oder langsamen Platte.
Lösung: falloc (oder trunc), höherer Disk-Cache und weniger Verbindungen.
aria2c --file-allocation=falloc --disk-cache=64M -x 8 -s 8 URL
Erwartet: Die Auslastung ist gleichmäßiger und das System bleibt bedienbar.
Windows: „path is too long“ / Datei kann nicht erstellt werden
Symptom: Lange Torrent-/Dateinamen scheitern unter Windows.
Ursache: Das klassische MAX_PATH-Limit von 260 Zeichen.
Lösung: --dir verkürzen oder lange Pfade in Windows aktivieren.
aria2c -d C:\dl URL
Erwartet: Die Datei wird innerhalb des Pfadlimits erstellt.
Fortsetzen startet bei 0%
Symptom: Ein erneuter Aufruf beginnt von vorn.
Ursache: Fehlendes -c, umbenannte/verschobene Datei oder fehlende Kontrolldatei.
Lösung: file.ext + file.ext.aria2 zusammenhalten und mit -c starten.
aria2c -c -x 16 -s 16 URL
Erwartet: aria2 setzt bei den vorhandenen Teilen fort.
Die .aria2-Datei wird nach 100% nicht gelöscht
Symptom: file.ext.aria2 bleibt nach Abschluss liegen.
Ursache: BitTorrent-Seeding läuft noch, oder die Integritätsprüfung scheiterte.
Lösung: Seeding stoppen/Aufgabe entfernen oder die Datei prüfen.
aria2c -c --check-integrity=true URL
Erwartet: Sobald die Datei versiegelt ist, entfernt aria2 die Kontrolldatei. Siehe .aria2-Leitfaden.
„Die Datei ist beschädigt“ beim Öffnen eines Teil-Downloads
Symptom: Ein Player oder Archiver lehnt die unvollständige Datei ab.
Ursache: Die Datei ist einfach nicht fertig (die .aria2-Datei ist noch da).
Lösung: Download fortsetzen; die Kontrolldatei nicht löschen.
Erwartet: Nach Abschluss ist die Datei gültig.
Downloads verschwinden nach einem Neustart
Symptom: Ein Neustart von aria2 verliert Warteschlange/Fortschritt.
Ursache: Keine Session-Persistenz konfiguriert.
Lösung: Session-Datei und Intervall konfigurieren.
save-session=/config/aria2.session
input-file=/config/aria2.session
save-session-interval=60
continue=true
Erwartet: aria2 lädt die Warteschlange und setzt beim Start fort.
aria2 startet nicht: „Failed to open the file …aria2.session, cause: File not found“
Symptom: aria2 beendet sich sofort mit errorCode=1 Failed to open the file …/aria2.session; ein Docker-Container startet ständig neu.
Ursache: input-file verweist auf eine noch nicht vorhandene Session-Datei. aria2 legt sie erst bei save-session an, startet aber ohne sie nicht. aria2 expandiert in diesem Pfad ${HOME}, aber nicht ~.
Lösung: Leere Datei einmalig anlegen und in der aria2.conf einen absoluten Pfad oder ${HOME} verwenden.
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
Erwartet: aria2 startet mit leerer Warteschlange und speichert/lädt sie danach automatisch.
„Downloading same file/info hash at that moment“ (Exit 11/12)
Symptom: aria2 weigert sich, eine doppelte Aufgabe hinzuzufügen.
Ursache: Dieselbe URI oder derselbe Torrent ist bereits in der Warteschlange.
Lösung: Die vorhandene Aufgabe verwalten (oder den Ausgabenamen ändern).
Erwartet: Es existiert nur eine Instanz der Aufgabe.
Downloads sind viel langsamer als meine Verbindung
Symptom: Geschwindigkeit weit unter Ihrer Bandbreite.
Ursache: aria2s HTTP-Standard ist eine Verbindung pro Server.
Lösung: Verbindungen und Splits erhöhen.
aria2c -x 16 -s 16 -k 1M URL
# HDD: zusätzlich --file-allocation=falloc
Erwartet: Die Geschwindigkeit steigt Richtung Leitungsrate. Siehe Geschwindigkeits-Leitfaden.
Geschwindigkeit hängt bei einem festen Wert
Symptom: Die Geschwindigkeit bleibt bei einer runden Zahl (z. B. genau 5 MB/s).
Ursache: Ein Limit ist gesetzt (0 = unbegrenzt).
Lösung: Download-/Upload-Limits löschen.
max-overall-download-limit=0
max-download-limit=0
max-overall-upload-limit=0
Erwartet: Die Geschwindigkeit wird nur von Netzwerk/Platte begrenzt.
aria2 braucht zu viel Speicher oder CPU
Symptom: Hoher RAM- oder CPU-Verbrauch beim Download.
Ursache: Sehr hoher disk-cache, hunderte Verbindungen oder riesige Peer-Zahlen.
Lösung: Cache und Verbindungs-/Peer-Limits senken.
aria2c --disk-cache=32M -x 8 -s 8 --max-concurrent-downloads=3 -j 3 URL
Erwartet: Der Ressourcenverbrauch sinkt bei akzeptabler Geschwindigkeit.
„Download aborted because speed was too slow“ (Exit-Code 5)
Symptom: aria2 gibt eine langsame Quelle auf.
Ursache: lowest-speed-limit ist für diesen Server zu hoch.
Lösung: Limit senken oder entfernen.
aria2c --lowest-speed-limit=0 URL
# oder sanfte Untergrenze: --lowest-speed-limit=1K
Erwartet: Der Download läuft trotz langsamer Quelle weiter.
„Bad or unrecognized option“ (Exit-Code 28)
Symptom: aria2 startet mit einem Optionsfehler nicht.
Ursache: Ein Tippfehler, ein falscher Schlüssel oder ein älterer Build ohne die Option.
Lösung: Den Schlüssel in der Optionsreferenz prüfen und aria2 aktualisieren.
Erwartet: aria2 parst die Konfiguration und startet.
Meine aria2.conf wird ignoriert
Symptom: Einstellungen in der Datei haben keine Wirkung.
Ursache: Die Datei liegt am falschen Ort, hat einen falschen Namen, oder Kommandozeilen-Flags überschreiben sie.
Lösung: Korrekten Pfad nutzen; Kommandozeilenoptionen haben Vorrang.
# Linux/macOS: ~/.aria2/aria2.conf
# Windows: %USERPROFILE%\.aria2\aria2.conf
aria2c --conf-path=/pfad/zu/aria2.conf
Erwartet: Die konfigurierten Optionen wirken beim Start.
Windows: Optionen in --downloader-args werden ignoriert
Symptom: Durch yt-dlp übergebene aria2-Flags wirken nicht.
Ursache: Shell-Quoting hat den aria2c:-Wert getrennt.
Lösung: Den ganzen Wert in doppelte Anführungszeichen setzen; keine Quote-Typen mischen.
yt-dlp --downloader aria2c --downloader-args "aria2c:-x 16 -s 16 -k 1M" URL
Erwartet: Die Flags erreichen aria2 und die Geschwindigkeit steigt.
Ist es gefährlich, Port 6800 zu öffnen?
Symptom: Der RPC-Port ist aus dem Internet erreichbar.
Ursache: rpc-listen-all=true plus Router-Portfreigabe oder öffentliche IP.
Lösung: 6800 nie öffentlich öffnen. Auf localhost/LAN halten und VPN oder authentifizierten HTTPS-Reverse-Proxy nutzen.
# lokal halten:
rpc-listen-all=false
# bei Aktivierung immer starkes Token:
rpc-secret=lang-zufaellig
Erwartet: Nur vertrauenswürdige Netze erreichen den RPC.
rpc-allow-origin-all lässt jede Webseite meinen Daemon steuern
Symptom: Sie haben CORS für das WebUI aktiviert und sorgen sich um Exposition.
Ursache: Mit offenem CORS kann jede besuchte Seite den RPC aufrufen, wenn sie den Port erreicht.
Lösung: Port privat halten, starkes Secret nutzen, lokale Seite/Proxy statt Port-Exposition bevorzugen.
Erwartet: Das WebUI funktioniert, ohne dass eine fremde Seite den RPC erreicht.
Sicherheit: Torrents, Metalinks und .aria2-Dateien aus unbekannter Quelle
Symptom: Sie wollen aus einer nicht vertrauenswürdigen Quelle laden.
Ursache: Torrents/Metalinks können auf Schadcode zeigen; eine fremde .aria2-Datei ist nicht vertrauenswürdig.
Lösung: Offizielle Quellen bevorzugen, Prüfsummen/Signaturen verifizieren und nie eine .aria2-Datei für eine andere Datei wiederverwenden.
aria2c --check-integrity=true --checksum=sha-256=HEXDIGEST URL
Erwartet: Der Hash der Datei stimmt mit dem veröffentlichten Digest überein.
Kein passendes Problem gefunden. Versuchen Sie ein anderes Stichwort oder sehen Sie in die Dokumentation.