> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localmind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging

> Debugging-Techniken und Fehlerbehebung für Automate-Workflows

Wenn ein Workflow nicht das tut, was er soll, führt der Weg fast immer über dieselbe Methode: Execution Logs lesen, das Problem isolieren, Nodes einzeln testen. Diese Seite zeigt das Vorgehen und die häufigsten Fehlerbilder samt Lösung.

## Execution Logs

Execution Logs sind die wichtigste Informationsquelle beim Debugging. Sie öffnen sie über den Tab **Executions**: Execution auswählen, anklicken und die einzelnen Nodes öffnen. Pro Node sehen Sie:

* **Input:** Daten, die der Node empfangen hat
* **Output:** Daten, die der Node produziert hat
* **Execution Time:** wie lange der Node gebraucht hat
* **Status:** Erfolg oder Fehler
* **Error Messages:** detaillierte Fehlermeldungen

Fehler erkennen Sie an roten Nodes (fehlgeschlagen), gelben Nodes (Workflow wartet), fehlenden Verbindungen, Timeout-Meldungen und API-Fehlern (4xx, 5xx).

<Tip>
  Filtern Sie die Executions-Liste nach fehlgeschlagenen Executions — das beschleunigt die Suche deutlich.
</Tip>

## Häufige Probleme und Lösungen

### Workflow läuft nicht

| Ursache                                 | Lösung                                                                                                                                 |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Workflow ist nicht aktiviert            | Prüfen Sie den **Active**-Toggle oben rechts und die Trigger-Konfiguration.                                                            |
| Trigger nicht konfiguriert              | Trigger-Konfiguration prüfen, Trigger manuell testen, Credentials für den Trigger (z.B. IMAP) sowie Webhook-URL und Secret validieren. |
| Credentials fehlen oder sind abgelaufen | Credentials in den Node-Einstellungen prüfen und einzeln testen; auch Environment Variables kontrollieren.                             |

### Daten werden nicht korrekt übergeben

| Ursache                      | Lösung                                                                                                                                                |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Falsche Expression-Syntax    | Syntax prüfen (`{{ $json.fieldName }}`) — Feldnamen sind case-sensitive. Expressions im Expression-Editor validieren und mit **Execute Node** testen. |
| Datenformat-Inkompatibilität | Datenformate zwischen Nodes prüfen, mit Set Nodes transformieren, mit JSON Schema validieren; tatsächliche Formate in den Execution Logs nachsehen.   |
| Node-Reihenfolge falsch      | Workflow-Struktur prüfen: Daten-Nodes müssen vor den Nodes kommen, die die Daten verwenden. Set Nodes zur Datenvorbereitung nutzen.                   |

Korrekte Expression-Syntax im Überblick:

```javascript Korrekte Syntax theme={null}
// Zugriff auf vorherige Node-Daten
{{ $json.email }}
{{ $json.user.name }}

// Zugriff auf spezifischen Node
{{ $('Node Name').item.json.field }}

// Funktionen
{{ $json.text.toUpperCase() }}
{{ $now.toISO() }}
```

### Agent gibt keine Antwort

Localmind-Agenten rufen Sie über die **HTTP Request Node** gegen `POST /v1/chat/completions` auf ([Anleitung](/automate/Localmind-Agent)) — die häufigsten Fehlerquellen liegen im Request selbst:

| Symptom                                                       | Lösung                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `404 {"detail":"Model '…' not found"}`                        | Das `model`-Feld im Request-Body muss eine **Agent-UUID** aus `GET /v1/models` enthalten, kein Modellname wie `gpt-4`. UUID gegen die Ausgabe von `GET /v1/models` abgleichen. Agenten außerhalb des API-Key-Scopes erscheinen dort nicht und sind nicht aufrufbar. |
| 404 auf die URL selbst                                        | Host prüfen: aus dem Browser kopierte URLs enthalten `-app` — ersetzen Sie `-app` durch `-api`. Pfad exakt `/v1/chat/completions` (mit `/v1`-Prefix).                                                                                                               |
| `401 Unauthorized` / Agent nicht sichtbar in `GET /v1/models` | Header-Auth-Credential prüfen: `Authorization: Bearer <LOCALMIND_API_KEY>` — das `Bearer `-Präfix nicht vergessen. Key-Scope prüfen: ist er auf Spaces beschränkt, die den Agenten nicht enthalten?                                                                 |

Alle Stolperfallen beim Agent-Aufruf im Detail: [Localmind Agent in n8n einbinden](/automate/Localmind-Agent#stolperfallen).

## Debugging-Techniken

### Nodes einzeln testen

1. Node öffnen, Test-Daten verwenden und auf **Execute Node** klicken.
2. Input prüfen: Datenformat validieren, auf fehlende Felder achten.
3. Output prüfen: erwartetes Format validieren, auf unerwartete Werte achten.

### Den gesamten Workflow debuggen

1. Aktivieren Sie **Save Data on Error** in den Workflow-Einstellungen — so bleiben Input/Output-Daten auch bei Fehlern für die Analyse erhalten.
2. Führen Sie den Workflow mit realistischen Test-Daten aus, damit das Fehlerbild dem Produktivbetrieb entspricht.
3. Identifizieren Sie in den Execution Logs die fehlgeschlagenen Nodes.
4. Testen Sie jeden Fix isoliert mit **Execute Node**, bevor Sie den nächsten angehen.
5. Führen Sie abschließend den gesamten Workflow erneut aus, um Seiteneffekte auszuschließen.

### Debug-Logging hinzufügen

```javascript Debug-Logging theme={null}
// Log wichtige Werte (Code Node: $json direkt, ohne Expression-Klammern)
console.log('User ID:', $json.userId);
console.log('Email:', $json.email);
console.log('Processing step:', 'email-sent');

// Log in Set Node
{
  "debug": {
    "step": "before-agent-call",
    "data": "={{ $json }}",
    "timestamp": "={{ $now.toISO() }}"
  }
}
```

## Debugging-Features in Automate

| Feature                | Zweck                                            |
| ---------------------- | ------------------------------------------------ |
| **Execute Node**       | Einzelne Nodes mit Test-Daten testen             |
| **Execution Logs**     | Detaillierte Logs für jede Execution             |
| **Save Data on Error** | Speichert Daten auch bei Fehlern für die Analyse |
| **Expression Editor**  | Validiert Expressions vor der Ausführung         |

## Häufige Fehlermeldungen

| Fehlermeldung               | Lösung                                                                                         |
| --------------------------- | ---------------------------------------------------------------------------------------------- |
| `Request timeout after 30s` | Timeout-Wert erhöhen, API-Call optimieren, [Retry-Logik](/automate/Retry-Logic) implementieren |
| `401 Unauthorized`          | Credentials prüfen, Token-Ablauf prüfen, API-Key-Format validieren                             |
| `Invalid data format`       | Datenformat prüfen, mit Set Node transformieren, mit JSON Schema validieren                    |

## Debugging-Checkliste

* [ ] Execution Logs wurden überprüft
* [ ] Fehlgeschlagene Nodes wurden identifiziert
* [ ] Jeder fehlgeschlagene Node wurde einzeln getestet
* [ ] Input/Output-Daten wurden validiert
* [ ] Expressions wurden auf Syntax-Fehler geprüft
* [ ] Datenformate wurden überprüft
* [ ] Credentials wurden validiert
* [ ] Error Messages wurden gelesen und verstanden

Weiterführend: [Testing](/automate/testing) und [Performance](/automate/performance).