9. Hilfe
9.1 Wenn etwas nicht funktioniert
Auf einem neuen PC zuerst der „Zustand des Kits“. Dann die häufigsten Probleme, die Meldung, die du siehst, und was zu tun ist: Downloads, belegte Ports, Server, die nicht starten, abgelaufene Anmeldungen. Und wie du ein Problem mit dem Diagnose-Zip meldest.
Kurz gesagt
- Such die Meldung, die du siehst, im Feld unten: Die Anleitung sammelt die häufigsten, mit der Abhilfe.
- Fast jeder Fehler hat einen Tooltip beim Darüberfahren mit der Maus und eine Zeile in der Ausgabe oder im Log, die mehr verrät.
- Das Log der App liegt in data\app\logs\app.log; die der Server daneben.
Zustand des Kits
Auf einem neuen PC, oder mit dem Kit auf einem anderen Stick, sieh zuerst unter Einstellungen › „Das Kit“ › „Zustand des Kits“ nach: eine Zeile pro Prüfung, grün wenn alles passt, gelb für eine Warnung, rot für einen Fehler, und darunter, was zu tun ist. „Erneut prüfen“ wiederholt die Prüfungen nach einer Korrektur.
- Das Laufwerk. FAT32 nimmt Dateien bis 4 GB (keine großen lokalen Modelle oder Datenbankkopien) und keine Links: Für ein Kit auf einem Stick ist exFAT besser, oder NTFS, wenn es unter Windows bleibt. Unter macOS und Linux lässt ein mit noexec eingehängtes Laufwerk (oder FAT32 mit showexec unter Linux) kein Programm starten: Die Zeile nennt den Befehl, um es neu einzuhängen.
- Der freie Platz: unter 5 GB eine Warnung, unter 1 GB ein Fehler (Installationen, Downloads und Datenbankkopien schlagen fehl). Schaffe Platz oder verschiebe das Kit auf ein größeres Laufwerk.
- Der Pfad des Kits: &, %, !, ^, Anführungszeichen sowie Umlaute und Buchstaben außerhalb des lateinischen Alphabets bringen cmd, PowerShell, Maven und Gradle durcheinander. Verschiebe das Kit in einen Ordner mit nur Buchstaben, Ziffern, Bindestrichen und Leerzeichen.
- Von einem anderen Konto privat gemachte Dateien, oft auf einem anderen PC: Das Kit kann sie nicht lesen (Einstellungen, Schlüssel, Anmeldungen der Agenten). Die Zeile nennt den Befehl, um sie zurückzuholen, auszuführen in einem Administrator-Terminal: takeown und icacls unter Windows, sudo chown unter macOS und Linux. Die App führt ihn nicht selbst aus, weil Administratorrechte nötig sind.
- Unter Linux die Bibliotheken des Systems: libaio und libnuma für MySQL, libicu für .NET, libvulkan1 für die Grafikkarte der lokalen Modelle (ohne sie bleiben sie auf der CPU). Die Zeile nennt den Befehl, um sie zu installieren, zum Beispiel mit apt.
- In der Kommandozeile macht
.\Atollo.exe check --kit | Out-Hostdieselben Prüfungen und endet mit 1, wenn eine davon ein Fehler ist.
Download und Installation
Eine Komponente bleibt auf „Fehler“ mit „fehlgeschlagen“ und einer Netzwerk- oder Zertifikatsmeldung.
Oft liegt es am Netzwerk: ein Firmen-Proxy oder die HTTPS-Untersuchung. Fülle Einstellungen › Netzwerk aus und versuche es erneut. Wenn das nicht reicht, verwende den Bereich „Im Browser herunterladen“ unter der Zeile und übergib die Datei dem Kit.
Mehr dazu: Firmennetzwerk: Proxy, Zertifikate, lokales Netzwerk (6.3)
„in Verwendung: Schließe die Programme des Kits und versuche es erneut“
Ein Programm des Kits (ein gestartetes Projekt, eine Konsole, der Editor, eine Datenbank) verwendet die zu ersetzenden Dateien. Stoppe es, schließe die Konsolen und versuche es erneut. Wenn du nicht weißt, was geöffnet ist, listet die Seite „Laufwerk entfernen“ es auf.
Mehr dazu: Das Laufwerk sicher entfernen (7.1)
„Es läuft bereits eine Installation.“ oder „Es läuft bereits eine Installation“
Warte, bis sie fertig ist (die Statusleiste zeigt den Schritt), oder klicke in der Leiste „Übernehmen“ auf „Abbrechen“.
Eine Komponente ist „zu aktualisieren“ (gelbes Dreieck).
Unter macOS und Linux müssen nach dem Verschieben des Kits einige Komponenten neu installiert werden: Das Kit erledigt das beim Start selbst. Wenn es so bleibt, klicke unten auf der Seite Werkzeuge auf „Alle aktualisieren“.
Mehr dazu: Auf einem anderen PC, unter einem anderen Buchstaben, in einem anderen Ordner (7.2)
Ein Programm stürzt ab oder eine Bibliothek fehlt, mit dem Kit auf einem USB-Stick.
Eine Datei des Programms kann auf dem Stick beschädigt sein. Klicke auf der Seite Werkzeuge auf „Dateien prüfen“ (oder führe check --files aus): Die Liste zeigt die Ordner mit fehlenden oder seit der Installation geänderten Dateien, und „Neu installieren“ stellt sie in derselben Version wieder her, ohne Projekte und Datenbanken anzurühren.
Mehr dazu: Die Seite Werkzeuge (5.1)
Projekte und Websites
„Port bereits … zugewiesen“, „Port … gehört bereits zum Server/zur Datenbank/zum Projekt …: Wähle einen anderen.“, „Die Ports 7000 bis 7099 gehören dem Editor“ oder ein Programm, das meldet, dass der Port belegt ist.
Ein Port gehört nur einem: einer Aktion eines Projekts, einem Pool der Seite Webserver, einer Version einer Datenbank oder dem Editor (7000-7099). Die Meldung sagt, wer ihn schon hat: „Port bereits … zugewiesen“ eine andere Aktion, „gehört bereits zum Server …“ ein Pool, „gehört bereits zur Datenbank …“ eine Version von MySQL oder MongoDB, „gehört bereits zum Projekt …“ eine Aktion. Das gilt für den Port einer Aktion, eines Pools und einer Datenbankversion. Hat dagegen ein Programm des PCs den Port, meldet es das selbst. Leere bei einer Aktion das Feld „Port“, um zum automatischen Port zurückzukehren; sonst wähle einen anderen zwischen 1024 und 65535.
Eine Aktion stoppt sofort mit „Fehler (Code 1)“.
Lies die letzten Zeilen der Ausgabe: Meist sagen sie, was fehlt. Häufige Fälle: nicht installierte Abhängigkeiten (führe zuerst npm install oder composer install aus), eine fehlende Komponente (Abschnitt „Komponenten“ › „Fehlendes installieren“), eine falsche Version (Abschnitt „Versionen“).
„Aktion nicht gefunden: Klicke auf Aktualisieren“
Das Projekt hat sich geändert (zum Beispiel panel.json). Klicke auf der Seite des Projekts auf „Aktualisieren“.
„panel.json ist kein gültiges JSON: ignoriert.“
In der Datei ist ein Syntaxfehler (ein Komma zu viel, ein fehlendes Anführungszeichen). Korrigiere ihn im Editor und klicke auf „Aktualisieren“.
„Der gemeinsame Server … ist nicht gestartet: siehe die Seite Webserver.“
Öffne die Seite Webserver, wähle den Pool und sieh dir den Fehler an. Oft ist der Port belegt: Ändere den Port des Profils, oder wähle „Eigener Server“ im Abschnitt „Website“ des Projekts.
Mehr dazu: Websites und .localhost-Adressen (3.3)
Die Website öffnet sich, zeigt aber alte Dateien oder eine leere Seite.
Prüfe den Ordner unter „Als Website bereitzustellender Ordner“ (bei vielen PHP-Frameworks ist es public) und lade die Seite im Browser ohne Cache neu (Strg+F5).
Der Editor bemerkt geänderte Dateien nicht.
Unter Windows passiert das, wenn ein Ordner im Pfad des Kits mit einer Ziffer, mit x oder mit u beginnt: Die App weist mit einem Hinweis darauf hin. Verschiebe das Kit in einen anderen Pfad.
Mehr dazu: Der erste Start (1.2)
Datenbanken
„Port … wird bereits von einem anderen Programm verwendet: Ändere ihn unten.“
Auf dem PC läuft ein anderes MySQL oder MongoDB (separat installiert) auf demselben Port. Ändere den „Port“ auf der Seite des Servers (zum Beispiel 3307) und starte ihn erneut; schreib dann die Verbindung mit „In .env schreiben“ neu in die .env der Projekte.
Mehr dazu: Die Datenbankserver (3.1)
Der Server bleibt nach dem Start auf „Fehler“.
Die Seite des Servers zeigt den letzten Fehler und den Pfad des Logs (data\app\logs). Unter Linux kann MySQL die Bibliotheken libaio und libnuma verlangen: Die Meldung nennt den Befehl, um sie zu installieren.
Das Projekt verbindet sich nicht mit der Datenbank.
Prüfe, ob der Server „Läuft“, und verwende dann „In .env schreiben“ im Abschnitt „Datenbanken“ des Projekts: Die .env enthält dann den richtigen Benutzer, das Passwort und den Port. Wenn das Projekt eine andere Version des Servers verwendet, ist der Port anders (3307…).
Mehr dazu: Die Datenbank eines Projekts (3.2)
Agenten, Git und GitHub
„Anmeldung abgelaufen“ bei den Agenten.
Öffne den Agenten in einem Projekt: Er erneuert die Anmeldung oder fordert dich auf, dich neu anzumelden.
Mehr dazu: Die Agenten: Claude Code, Codex, Antigravity, Pi (4.1)
Git meldet „Please tell me who you are“ beim ersten Commit.
Gib Name und E-Mail unter Einstellungen › „GitHub-Konto“ › „Wer die Commits signiert“ ein oder melde dich bei GitHub an: Wenn sie leer sind, füllt das Konto sie aus. In einem Terminal des Kits funktionieren auch git config --global user.name und user.email.
Mehr dazu: Das GitHub-Konto des Kits (6.1)
„GitHub hat die Anmeldung abgelehnt: Melde dich erneut an.“
Das Token ist nicht mehr gültig (widerrufen oder abgelaufen). Klicke unter Einstellungen › „GitHub-Konto“ auf „Abmelden“ und dann auf „Bei GitHub anmelden“.
Mehr dazu: Das GitHub-Konto des Kits (6.1)
Start der App
„Das Laufwerk des Kits ist schreibgeschützt: In den Ordner … kann nicht geschrieben werden.“
Der USB-Stick ist schreibgeschützt (manchmal gibt es einen Schalter) oder schreibgeschützt eingehängt. Das Kit muss in seinen Ordner schreiben können.
macOS: „macOS hat Atollo aus einer temporären, schreibgeschützten Kopie geöffnet (App Translocation)“.
Das passiert bei heruntergeladenen, nicht beglaubigten Apps. Die Meldung zeigt einen xattr-Befehl: Führe ihn im Terminal aus und öffne Atollo erneut.
Mehr dazu: Auf einem anderen PC, unter einem anderen Buchstaben, in einem anderen Ordner (7.2)
Linux: Das Laufwerk ist mit noexec eingehängt, oder WebKitGTK fehlt.
Die Meldung erklärt, was zu tun ist: Häng das Laufwerk mit Ausführungsrecht neu ein, oder installiere die angegebenen Pakete.
Windows: WebView2 fehlt.
WebView2 ist die Windows-Komponente, die das Fenster zeichnet; sie ist in Windows 11 bereits vorhanden und fast immer auch in Windows 10. Fehlt sie, zeigt Atollo den Link zum Installieren.
Hinweis: „Auf diesem PC sind Programme einer anderen Kopie des Kits geöffnet“.
Nur eine Information: Ein anderes Kit ist geöffnet. Die beiden Kopien teilen nichts.
Wenn das Problem nicht hier steht
- Lies die Ausgabe der Aktion (Abschnitt „Start“) oder das Log des Servers: Die letzte Zeile nennt meist die Ursache.
- Schließe Atollo und öffne es erneut: Vieles (Umgebung, Agenten, Dateien des Kits) wird bei jedem Start neu erzeugt.
- Prüfe die Komponenten mit „Prüfen“ auf der Seite Werkzeuge oder mit
.\Atollo.exe check | Out-Host. - Wenn es immer noch nicht klappt, melde es: Der Abschnitt unten erklärt, wie.
Ein Problem melden
Unter Einstellungen › „Das Kit“ › „Ein Problem melden“ gibt es zwei Schaltflächen, in dieser Reihenfolge zu verwenden.
- „Diagnose exportieren“ erstellt auf dem PC das Zip atollo-diagnostica-<Datum-Uhrzeit>.zip in data\app\diagnostics: Version und System, Laufwerk des Kits (Dateisystem, Art, freier Platz), RAM, Umgebung des Kits, die Prüfung der Programme, die Komponenten, die Ports und das Ende jedes Logs. „Ordner öffnen“ zeigt es. In der Kommandozeile macht
.\Atollo.exe diagnostics | Out-Hostdasselbe. - Bevor das Zip geschrieben wird, wird jedes Geheimnis, das das Kit aufbewahrt (die Schlüssel in data\app\secrets, das Token von Claude Code, die Datenbankpasswörter, die Anmeldungen der Agenten, das GitHub-Token), überall durch *** ersetzt; dein Profilordner wird zu ~, dein Benutzername und der Name des PCs zu ***. Öffne es trotzdem und sieh es dir an, bevor du es anhängst: Ein Projekt kann Dinge in die Logs schreiben, die das Kit nicht kennt.
- „Problem melden“ öffnet im Browser ein neues Issue auf github.com/nabre/atollo mit dem Fehlerformular: Version von Atollo und System (Kit, Windows-Build, Dateisystem und Art des Laufwerks) sind schon eingetragen. Beschreibe, was passiert ist und die Schritte, um es nachzustellen, und zieh das Zip in das Issue.
- Die App sendet nichts: Das Zip bleibt auf dem PC, bis du es anhängst, und das Issue erreicht GitHub erst, wenn du auf „Create“ klickst (ein GitHub-Konto ist nötig). Ab dann gelten die Datenschutzregeln von GitHub, und das Issue ist öffentlich.