# Fehlerbehebung

> Lösungen für häufige Probleme: ducklocal nicht gefunden, Dateien, die nicht angehängt werden, Datenbanken, die nicht öffnen, hängende Abfragen, S3.

Source: https://ducklocal.app/docs/de/troubleshooting

Suchen Sie das Symptom, lesen Sie die Ursache und wenden Sie die Lösung an. Wenn Ihr Problem nicht aufgeführt ist, [eröffnen Sie ein Issue](https://github.com/JetSquirrel/DuckLocal/issues) mit Details dazu, was Sie getan haben und was passiert ist.

## Installieren und Starten

| Symptom | Ursache und Lösung |
| --- | --- |
| Die App öffnet sich auf einem Intel-Mac nicht | Das macOS-Release ist nur für Apple silicon gebaut. [Bauen Sie auf Intel aus dem Quellcode](development.md#build-and-run) |
| Die Tastenkürzel in dieser Doku tun unter Windows oder Linux nichts | Denken Sie **Ctrl** statt **⌘**: ⌘↵ ist dort Ctrl+Enter |
| `ducklocal: command not found` | Das Disk-Image installiert die App, keinen Befehl. [Verlinken Sie die Binary in Ihren PATH](getting-started.md#add-command) |
| Das Terminal ist belegt, solange das Fenster offen ist | Wenn Sie die GUI aus einem Terminal starten, läuft sie im Vordergrund. Starten Sie stattdessen über Programme, oder lassen Sie dieses Terminal dafür offen |
| Verlauf, Einstellungen oder gemerkte Dateien werden nicht mehr gespeichert | Ein zweites DuckLocal läuft und hält die App-Datendatei. Beenden Sie das andere und starten Sie neu |
| **DuckLocal wurde beim letzten Mal unerwartet beendet** | Es ist abgestürzt und hat einen Bericht im Logs-Ordner gespeichert. Klicken Sie auf **Bericht anzeigen** und hängen Sie ihn an ein [Issue](https://github.com/JetSquirrel/DuckLocal/issues) — siehe [wo alles gespeichert wird](settings-and-data.md#where-things-are-stored) |
| **Update-Prüfung fehlgeschlagen** | Fahren Sie mit der Maus darüber, um den Grund zu sehen: offline, ein Proxy oder ein Download, dessen Prüfsumme nicht passte. Klicken Sie, um es erneut zu versuchen, oder laden Sie das Release von GitHub — siehe [Update-Prüfung](settings-and-data.md#update-check) |

## Daten öffnen

| Symptom | Ursache und Lösung |
| --- | --- |
| `File not found` bei einem Pfad, den Sie angegeben haben | Der Pfad existiert nicht oder ist relativ zu einem anderen Verzeichnis als gedacht. Verwenden Sie einen absoluten Pfad, um sicher zu sein |
| Ein Ordner meldet keine Datendateien | Nichts darunter passte auf `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.ndjson`, `.jsonl`, `.xlsx`, `.xls`, `.xlsb` oder `.ods` |
| Ein Ordner hat weniger Dateien geliefert als erwartet | Versteckte Einträge und Symlinks werden übersprungen, und eine Öffnungsanfrage hängt höchstens 256 Dateien an. Öffnen Sie Unterordner einzeln |
| Ein Pfad wurde unerwartet als Datenbank geöffnet | Jede vorhandene Datei, die keine Datendatei ist, wird als DuckDB-Datenbank behandelt. Lässt sie sich nicht öffnen, sagt DuckLocal warum; beim Start fällt es auf den Speicher zurück. Siehe [Eine Datenbank öffnen](#opening-a-database) |
| **Nicht angehängt …: die Datenbank hat bereits eine Tabelle oder View mit dem Namen …** | Die Datenbank enthält bereits eine Tabelle oder View mit demselben Namen wie die gemerkte Datei. DuckLocal ersetzt sie nie. Benennen Sie eine der beiden um, löschen Sie sie, oder entfernen Sie die Datei aus **Lokale Dateien** und öffnen Sie sie erneut, um einen neuen Namen zu bekommen |
| **Relativen Pfad kann nicht wiederhergestellt werden …** | Eine Datei wurde mit einem relativen Pfad gemerkt, der sich in einer neuen Sitzung nicht auflösen lässt. Entfernen Sie sie aus **Lokale Dateien** und öffnen Sie sie erneut |
| Eine View heißt `sales_2` statt `sales` | Eine andere Datei oder Tabelle hatte den Namen schon, daher bekam die neue ein Suffix |
| Die View einer Datei ist veraltet | Views lesen die Datei bei jeder Abfrage. Wenn sich die Spalten einer CSV geändert haben, verwenden Sie **Schema aktualisieren** in der Seitenleiste |

## Eine Datenbank öffnen {#opening-a-database}

| Symptom | Ursache und Lösung |
| --- | --- |
| Die Meldung sagt, die Datenbank sei von einem neueren DuckDB erstellt worden | Die Datei verwendet ein Speicherformat, das neuer ist, als das eingebaute DuckDB von DuckLocal lesen kann. Führen Sie die Zeilen `ATTACH … COPY FROM DATABASE` aus der Meldung in dem DuckDB aus, das die Datei erstellt hat, und öffnen Sie dann die Kopie. Siehe [Wenn sich eine Datenbank nicht öffnen lässt](data-sources.md#when-a-database-will-not-open) |
| Die Meldung sagt, die Datenbank stamme aus DuckDB v0.9 oder älter | Führen Sie `EXPORT DATABASE 'dir'` mit dem DuckDB aus, das sie geschrieben hat, dann `IMPORT DATABASE 'dir'` in DuckLocal |
| Die Meldung sagt, es sei eine SQLite-Datenbank | Hängen Sie sie mit **Öffnen → Datenbank anhängen…** an, statt sie zu öffnen |
| Die Meldung sagt, die Datei sei keine DuckDB-Datenbank | Ihre Endung ist keine, die DuckLocal als Daten liest, daher wurde sie als Datenbank versucht. Geben Sie ihr eine [unterstützte Endung](data-sources.md#supported-file-formats), oder lesen Sie sie in SQL, zum Beispiel `SELECT * FROM read_csv('export.dat')` |
| DuckDB meldet, es konnte keine Sperre auf die Datei setzen | Ein anderes Programm — ein anderes DuckDB, ein Skript, eine zweite App — hat die Datenbank zum Schreiben geöffnet, und DuckDB lässt nur einen Prozess auf eine Datei schreiben. Schließen Sie sie dort und öffnen Sie die Datei dann erneut |
| DuckDB meldet Zugriff verweigert | Ihr Konto kann die Datei nicht lesen oder nicht schreiben: Die Hauptdatenbank wird zum Schreiben geöffnet. Korrigieren Sie die Rechte der Datei, oder hängen Sie sie mit aktiviertem **Schreibgeschützt** an |
| Ein Öffnen der Datenbank ist fehlgeschlagen und nichts hat sich geändert | Erwartet, solange DuckLocal läuft: Ein fehlgeschlagenes Öffnen hinterlässt den Workspace, den Sie hatten. Lesen Sie den Grund in der Benachrichtigung |
| Der Tooltip der Statusleiste sagt **lesbar für DuckDB v1.x+**, und eine Kollegin kann die Datei nicht öffnen | Ihr DuckDB ist älter als diese Version. Sie muss aktualisieren, oder Sie kopieren die Datei mit einem älteren `STORAGE_VERSION` — siehe [Welches DuckDB eine Datenbank lesen kann](data-sources.md#storage-version) |

## Angehängte Datenbanken

| Symptom | Ursache und Lösung |
| --- | --- |
| Eine angehängte Datenbank fehlt nach einem Neustart | Ihre Datei war beim Start nicht am gemerkten Pfad und wurde daher übersprungen. Die Registrierung bleibt erhalten; legen Sie die Datei zurück, und sie erscheint mit der nächsten Verbindung wieder |
| **Diese Datenbank ist bereits geöffnet, als …** | Die Datei ist bereits die Hauptdatenbank oder unter diesem Namen angehängt. Fragen Sie sie unter diesem Namen ab |
| **Konnte … nicht anhängen: der Name … ist in der geöffneten Datenbank vergeben.** | Etwas anderes in der Verbindung nutzt bereits den gemerkten Alias — zum Beispiel eine Datenbank, die Sie in SQL unter demselben Namen angehängt haben. Führen Sie `DETACH` für diese aus, und öffnen Sie die Datenbank dann erneut oder starten Sie neu |
| Schreiben in eine angehängte Datenbank schlägt fehl | Sie wurde schreibgeschützt angehängt, dem Standard. Wählen Sie **Datenbank trennen** in der Seitenleiste und hängen Sie sie erneut an, ohne **Schreibgeschützt** |
| Das Anhängen hat eine leere Datenbank erzeugt | Ohne **Schreibgeschützt** wird ein DuckDB-Pfad, der nicht existiert, angelegt. Trennen Sie sie, löschen Sie die leere Datei und prüfen Sie den Pfad |
| Ein Tabellenname ohne Datenbank findet die falsche Tabelle | Namen ohne Datenbank werden in der Standarddatenbank aufgelöst. Klicken Sie mit der rechten Maustaste auf eine Datenbank und wählen Sie **Als Standarddatenbank verwenden**, oder schreiben Sie `alias.table` |

## Finder und Quick Look

Diese gelten nur unter macOS.

| Symptom | Ursache und Lösung |
| --- | --- |
| Ein Doppelklick auf eine `.parquet`- oder `.duckdb`-Datei öffnet eine andere App | Diese App ist bereits die Standard-App. Wählen Sie im Finder **Informationen → Öffnen mit**, dann DuckLocal, dann **Alle ändern…** |
| Ein Doppelklick auf eine CSV- oder Excel-Datei öffnet DuckLocal nicht | Absicht: DuckLocal übernimmt diese nicht. Verwenden Sie **Öffnen mit → DuckLocal**, oder ziehen Sie die Datei auf das Dock-Symbol |
| DuckLocal wird unter **Öffnen mit** nicht angeboten, oder die Leertaste zeigt keine DuckLocal-Vorschau | macOS hat die App noch nicht registriert. Verschieben Sie sie nach Programme und starten Sie sie einmal. Führen Sie für die Vorschau danach `qlmanage -r` im Terminal aus, und prüfen Sie, ob **DuckLocal Preview** unter Quick Look in den Erweiterungseinstellungen der Systemeinstellungen aktiviert ist |
| Eine einfache `.json`- oder Excel-Datei zeigt keine DuckLocal-Vorschau | Absicht: Diese bleiben den eigenen Vorschauen von macOS überlassen. `.jsonl`- und `.ndjson`-Dateien werden in der Vorschau angezeigt |
| Die Vorschau zeigt nur 50 Zeilen | Absicht: Eine Vorschau liest nie die ganze Datei. Öffnen Sie die Datei in DuckLocal für den Rest |
| Die Vorschau einer `.duckdb`-Datei zeigt einen Fehler | Die Vorschau liest die Datei mit dem DuckDB von DuckLocal, daher scheitert eine Datei aus einem neueren DuckDB auch dort. Siehe [Eine Datenbank öffnen](#opening-a-database) |

## Abfragen ausführen

| Symptom | Ursache und Lösung |
| --- | --- |
| **Ausführen** tut nichts | Eine Abfrage läuft bereits. Drücken Sie **Stopp** neben Ausführen oder **⌘.**, um sie zu unterbrechen |
| Eine Abfrage ist mit `Interrupted` fehlgeschlagen | Jemand hat während der Ausführung **Stopp** (oder ⌘.) gedrückt. Führen Sie sie erneut aus |
| Ein Teil meines SQL hat eine rote Wellenlinie | Der letzte Lauf ist dort fehlgeschlagen. Lesen Sie die Meldung *Abfrage fehlgeschlagen*; die Markierung verschwindet beim nächsten Lauf |
| **⌘↵** zeigt den Editor, statt auszuführen | Im Erststart-Bildschirm bedeutet ⌘↵ „geben Sie mir einen Editor". Drücken Sie es erneut, um auszuführen |
| Die Ergebnisse enden früh mit einem Hinweis auf Kürzung | Die Grenze von 100.000 Zeilen bzw. 2.000.000 Zellen wurde erreicht. Grenzen Sie die Abfrage ein; eine Paginierung gibt es nicht |
| Zeitstempel wirken verschoben | Das Raster stellt Zeitstempel in UTC dar, nicht in Ortszeit |
| Ein `TIMETZ`-Wert hat seinen Offset verloren, oder ein `BIT`- oder `BIGNUM`-Wert sieht wie Bytes aus | Diese Typen lassen sich auf dem Weg zu DuckLocal nicht von gewöhnlichen Werten unterscheiden. `CAST(column AS VARCHAR)` in SQL zeigt den echten Wert |
| Sortieren holt keine Zeilen über die Vorschau hinaus | Das Sortieren über die Kopfzeile ordnet nur geladene Zeilen um. Verwenden Sie `ORDER BY` in SQL, um das ganze Ergebnis vor der Kürzung zu ordnen |
| Eine Abfrage braucht eine Erweiterung, die nicht installiert ist | Fehlende Erweiterungen werden nicht mehr automatisch heruntergeladen. Installieren Sie sie ausdrücklich im Tab **Erweiterungen**, und laden Sie sie dann oder führen Sie die Abfrage erneut aus |
| Eine Abfrage, die vor 0.3.0 funktionierte, meldet eine nicht installierte Erweiterung oder eine Funktion, die es nicht gibt | DuckLocal 0.3.0 verwendet DuckDB 2.0, das installierte Erweiterungen pro Release trennt. Installieren Sie sie erneut im Tab **Erweiterungen** — siehe [Erweiterungen](schema-and-history.md#extensions) |
| Ein bloßer Spaltenalias wie `minutes` verursacht einen Parser-Fehler | Es ist ein SQL-Schlüsselwort. Schreiben Sie `AS minutes`, oder setzen Sie ihn in Anführungszeichen: `SELECT count(*) AS "minutes" FROM events` |
| Ein Klick auf eine Tabelle oder einen Verlaufseintrag hat mein SQL überschrieben | Diese Klicks ersetzen den gesamten Editor-Puffer. Verwenden Sie für Experimente einen neuen Abfrage-Tab |
| Ein Export hat stillschweigend eine Datei ersetzt | Export schreibt ohne Nachfrage an den angegebenen Pfad. Wählen Sie einen neuen Namen |

## S3

| Symptom | Ursache und Lösung |
| --- | --- |
| S3-Zugangsdaten wurden vergessen | Sie gelten konstruktionsbedingt nur für die Sitzung, und das Öffnen oder Wechseln einer Datenbank löscht sie. Konfigurieren Sie S3 erneut |
| Das Konfigurieren von S3 schlägt offline fehl | Die erste Nutzung führt `INSTALL httpfs` aus, was die Erweiterung herunterlädt. Verbinden Sie sich einmal, dann ist sie zwischengespeichert |
| Temporäre (STS-)Zugangsdaten werden abgelehnt | Es wird kein Session-Token gesendet. Verwenden Sie langlebige Schlüssel — siehe [S3 und httpfs](s3.md#limitations) |
| Ein Bucket wirkt kleiner, als er ist | Die Auflistung endet bei 1.000 Einträgen pro Ebene. Fragen Sie stattdessen mit einem Glob wie `'s3://bucket/prefix/*.parquet'` ab |

## Dashboards

| Symptom | Ursache und Lösung |
| --- | --- |
| Ein Diagramm in einem Dashboard meldet, eine Abfrage müsse schreibgeschützt sein | Eine `.dash`-Abfrage hat versucht zu schreiben (DDL, DML, `COPY`, `ATTACH`, …). Dashboards führen nur schreibgeschützte Anweisungen aus; verlagern Sie das Setup in den SQL-Editor |
| Ein Agent hat meine Kommentare nicht gesehen | Kommentare werden nirgendwohin gesendet: Der Agent muss sie lesen. Bitten Sie ihn, `ducklocal comments FILE` auszuführen, oder „die Kommentare in FILE zu bearbeiten", wenn er die [offizielle Skill](cli.md#install-the-official-skill) hat |
| Die Antwort oder Änderung eines Agenten erscheint nicht | Das Fenster folgt sowohl der Spezifikation als auch `FILE.comments.json` innerhalb einer Sekunde. Eine Spezifikation, die nicht mehr validiert, behält das letzte funktionierende Dashboard, mit dem Grund darüber; öffnen Sie **Spezifikation anzeigen**, um die Datei zu sehen |
| Ein `PIVOT` in einem Dashboard wird abgelehnt | Ein `PIVOT` innerhalb eines `SELECT` oder `WITH` muss seine Werte nennen. Listen Sie sie auf: `PIVOT t ON channel IN ('Web', 'Store') USING sum(revenue)`, oder beginnen Sie die Abfrage mit dem `PIVOT` |

## Darstellung

| Symptom | Ursache und Lösung |
| --- | --- |
| Das Theme springt bei jedem Start auf Hell zurück | Das Theme wird zwischen Starts nicht gespeichert; die Sprache schon |
| Text oder Symbole sind zu klein oder zu groß | Verwenden Sie die Schaltfläche **Aa** in der Titelleiste oder ⌘+ / ⌘− / ⌘0. Siehe [Schnittstellengröße](settings-and-data.md#interface-size) |
| Die Oberfläche ist in der falschen Sprache | Verwenden Sie die Schaltfläche `EN` / `中` in der Titelleiste; die Auswahl wird gemerkt |

## Neu anfangen

Um Verlauf, gemerkte Dateien, offene Tabs und Einstellungen zu löschen, beenden Sie DuckLocal und
entfernen Sie sein App-Datenverzeichnis:

```bash
rm -rf ~/Library/Application\ Support/DuckLocal
```

Ihre Datendateien werden nie berührt — nur die eigenen Aufzeichnungen von DuckLocal werden entfernt. Was dort gespeichert wird, steht unter [Einstellungen und App-Daten](settings-and-data.md).
