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

# Fehlerbehebung

Beginnen Sie mit:

```bash theme={null}
kubectl -n fineparser get pods,pvc
kubectl -n fineparser get events --sort-by=.lastTimestamp | tail -30
```

## Health-Checks

Jede Komponente stellt `GET /healthz` auf Port 8080 als Readiness-Probe bereit. Ein betriebsbereiter pod antwortet mit `{"status":"ok"}`. Ein nicht betriebsbereiter pod antwortet mit `503`, liefert dabei `status` sowie den Grund in `error` zurück und läuft weiter, statt neu zu starten.

```bash theme={null}
kubectl -n fineparser port-forward deploy/fineparser-ingest 8081:8080
curl -s localhost:8081/healthz
```

| Komponente | Nicht bereit, solange |
| - | - |
| Orchestrator | Das Worker-Deployment wurde noch nicht über die Kubernetes-API gelesen. |
| Ingest | Ein Volume kann nicht verwendet werden oder der Orchestrator wurde noch nicht erreicht. |
| Worker | Die Engine wird gestartet, die Abrechnung ist noch nicht bestätigt oder das Standardprofil wurde abgelehnt. |

## Installation

### Ein Claim bleibt im Status Pending

```bash theme={null}
kubectl -n fineparser describe pvc <claim>
```

Beim in-process-Claim: Der EFS-CSI-Treiber fehlt, seinem Controller fehlt `AmazonEFSCSIDriverPolicy` oder `fileSystemId` ist falsch. Bei `mnesia-fineparser-orchestrator-0`: Der Cluster hat keine Standard-StorageClass oder deren Treiber fehlt.

### Pods hängen im Status ContainerCreating fest

Die Ursache lässt sich mit `kubectl describe pod` ermitteln.

* Zeitüberschreitung bei EFS-Mounts: In der Availability Zone des Knotens gibt es kein Mount-Ziel, oder TCP-Port 2049 ist blockiert.
* S3-Mounts schlagen fehl: Bucket oder Region ist falsch, oder die Rolle des Mountpoint-Treibers hat keinen Zugriff auf den Bucket. `No signing credentials available` bedeutet, dass die Vertrauensrichtlinie der Rolle nicht zum OIDC-Provider des Clusters passt.

### Pods schlagen mit „exec format error“ fehl

Der Pod befindet sich auf einem `arm64`-Knoten. Siehe [Auf amd64 ausführen](https://docs.abbyy.com/de/fine-parser/enterprise/best-practices/scheduling.md#run-on-amd64).

## Worker

### Worker starten nicht

```bash theme={null}
kubectl -n fineparser get deploy fineparser-worker
kubectl -n fineparser logs statefulset/fineparser-orchestrator | grep 'scaling workers'
```

Wenn das Deployment Worker anfordert, diese aber im Status Pending verbleiben, ist im Cluster kein Platz mehr: Prüfen Sie, ob Ihr Knoten-Autoscaler `amd64`-Knoten hinzufügen kann, die zu `worker.nodeSelector` und `worker.tolerations` passen. Wenn `worker.prepull` aktiviert ist, prüfen Sie außerdem, ob das Pre-Pull-DaemonSet auf den neuen Knoten läuft.

### Worker werden beim Starten beendet

```bash theme={null}
kubectl -n fineparser logs deploy/fineparser-worker --previous | grep billing
```

Die Zeile `billing refused this worker, exiting:` gibt den Grund an.

| Grund | Behebung |
| - | - |
| `AWS_ROLE_ARN is unset` oder `AWS_REGION is unset` | Das Dienstkonto hat keine Annotation `eks.amazonaws.com/role-arn`. Siehe [IAM und Abrechnung](https://docs.abbyy.com/de/fine-parser/enterprise/aws/iam-and-billing.md). |
| `AccessDenied` | Hängen Sie `AWSMarketplaceMeteringRegisterUsage` an die Rolle an. |
| Ein STS-Fehler | Die Vertrauensrichtlinie der Rolle stimmt nicht mit dem Cluster, dem Namensraum oder dem Dienstkonto überein. |
| `CustomerNotEntitled` | Das Konto hat kein aktives Abonnement. |
| Ein Zertifikatsfehler | Ein Proxy prüft den TLS-Verkehr zu `*.amazonaws.com`. Nehmen Sie diese Domain von der Prüfung aus. |

`billing: RegisterUsage failed, retrying` ist ein vorübergehender Fehler, bei dem der Worker den Vorgang automatisch wiederholt.

### Worker sind nicht bereit

Die FineReader Engine hat das Standardprofil abgelehnt. Den Grund finden Sie im Protokoll des Workers und unter `/healthz`. Korrigieren Sie `worker.predefinedProfile` oder `worker.userProfile`, führen Sie ein Upgrade durch und starten Sie die Worker neu.

### Worker starten mit Exit-Code 2 neu

Ein Worker, bei dem fünf Einheiten in Folge fehlschlagen, startet neu. Prüfen Sie das Feld `failure.message` der fehlgeschlagenen Jobs. Wenn alle Dokumente fehlschlagen, überprüfen Sie die Volumes oder das Profil.

## Jobs

| Symptom | Lösung |
| - | - |
| Jobs schlagen mit `timed-out` fehl | Erhöhen Sie `orchestrator.workLeaseSeconds` oder verringern Sie `ingest.pageSplitThreshold`. Siehe [Einheitengröße und Leases](https://docs.abbyy.com/de/fine-parser/enterprise/concepts/scaling.md#unit-size-and-leases). |
| Jobs schlagen mit `finalize-failed` fehl | Prüfen Sie, ob die Worker auf das Ausgabe-Volume schreiben können. |
| Anfragen schlagen mit `413` fehl | Erhöhen Sie `ingest.maxUploadSize` und setzen Sie `ingest.scratchSize` auf etwa den doppelten Wert. |
| Ingest-pods werden während des Hochladens entfernt (evicted) | Erhöhen Sie `ingest.scratchSize` oder verringern Sie `ingest.maxUploadSize`. |
| `GET /jobs/{jobId}` gibt für einen bekannten Job `404` zurück | Sein Status ist nach Ablauf von `orchestrator.jobRetentionSeconds` verfallen. Die Ergebnisse liegen weiterhin auf dem Ausgabe-Volume. |

## Upgrades

| Symptom | Lösung |
| - | - |
| Konflikt bei `.spec.replicas` | Führen Sie denselben `helm upgrade`-Befehl erneut aus. |
| Ein Upgrade schlägt bei einer StorageClass, einem PersistentVolume oder einem Claim fehl | Für diese Änderung ist eine Neuinstallation erforderlich. Siehe [Änderungen, die eine Neuinstallation erfordern](https://docs.abbyy.com/de/fine-parser/enterprise/best-practices/upgrades.md#changes-that-need-a-reinstall). |