> ## 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.

# Dépannage

Commencez par :

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

## Contrôles d’intégrité

Chaque composant expose `GET /healthz` sur le port 8080 en guise de sonde de disponibilité (readiness probe). Un pod prêt renvoie `{"status":"ok"}`. Un pod non prêt renvoie `503` avec `status` et le motif dans `error`, et continue de s’exécuter au lieu de redémarrer.

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

| Composant | Non prêt tant que |
| - | - |
| Orchestrator | Il n’a pas encore lu le Deployment des processus de traitement via l’API Kubernetes. |
| Ingest | Il ne peut pas utiliser de volume ou n’a pas encore pu joindre l’orchestrateur. |
| Worker | Le moteur est en cours de démarrage, la facturation n’est pas encore confirmée ou le profil par défaut a été refusé. |

## Installation

### Une demande de volume reste à l'état Pending

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

Pour la PVC in-process : le pilote CSI EFS est absent, son contrôleur ne dispose pas de `AmazonEFSCSIDriverPolicy`, ou la valeur de `fileSystemId` est incorrecte. Pour `mnesia-fineparser-orchestrator-0` : le cluster n’a pas de StorageClass par défaut, ou le pilote de celle-ci est absent.

### Les pods restent bloqués à l’état ContainerCreating

`kubectl describe pod` en indique la cause.

* Les montages EFS expirent : aucune cible de montage n’existe dans la zone de disponibilité du nœud, ou le port TCP 2049 est bloqué.
* Les montages S3 échouent : le compartiment ou la région est incorrect, ou le rôle du pilote Mountpoint ne peut pas accéder au compartiment. `No signing credentials available` signifie que la stratégie d’approbation du rôle ne correspond pas au fournisseur OIDC du cluster.

### Les pods échouent avec l'erreur exec format error

Le pod s'exécute sur un nœud `arm64`. Voir [Exécuter sur amd64](https://docs.abbyy.com/fr/fine-parser/enterprise/best-practices/scheduling.md#run-on-amd64).

## Unités de traitement

### Aucune unité de traitement ne démarre

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

Si le Deployment requiert des processus de traitement mais que ceux-ci restent à l'état Pending, c'est que le cluster manque de capacité : vérifiez que votre autoscaler de nœuds peut ajouter des nœuds `amd64` correspondant à `worker.nodeSelector` et `worker.tolerations`. Si `worker.prepull` est activé, vérifiez également que le DaemonSet de pré-téléchargement s'exécute bien sur les nouveaux nœuds.

### Les unités de traitement s'arrêtent au démarrage

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

La ligne `billing refused this worker, exiting:` indique le motif.

| Motif | Solution |
| - | - |
| `AWS_ROLE_ARN is unset` ou `AWS_REGION is unset` | Le compte de service ne possède pas d’annotation `eks.amazonaws.com/role-arn`. Voir [IAM et facturation](https://docs.abbyy.com/fr/fine-parser/enterprise/aws/iam-and-billing.md). |
| `AccessDenied` | Joignez la stratégie `AWSMarketplaceMeteringRegisterUsage` au rôle. |
| Une erreur STS | La stratégie d’approbation du rôle ne correspond pas au cluster, à l’espace de noms ou au compte de service. |
| `CustomerNotEntitled` | Le compte ne dispose d’aucun abonnement actif. |
| Une erreur de certificat | Un proxy inspecte le trafic TLS vers `*.amazonaws.com`. Excluez ce domaine de l’inspection. |

`billing: RegisterUsage failed, retrying` est une erreur temporaire : le processus de traitement effectue automatiquement une nouvelle tentative.

### Les unités de traitement ne sont pas prêtes

FineReader Engine a refusé le profil par défaut. Le journal du processus de traitement et `/healthz` en indiquent la cause. Corrigez `worker.predefinedProfile` ou `worker.userProfile`, effectuez la mise à niveau, puis redémarrez les unités de traitement.

### Les unités de traitement redémarrent avec le code de sortie 2

Un processus de traitement qui échoue sur cinq unités consécutives redémarre. Consultez le champ `failure.message` des tâches en échec. Si tous les documents échouent, vérifiez les volumes ou le profil.

## Tâches

| Symptôme | Solution |
| - | - |
| Les tâches échouent avec l’erreur `timed-out` | Augmentez `orchestrator.workLeaseSeconds` ou réduisez `ingest.pageSplitThreshold`. Voir [Taille des unités et baux](https://docs.abbyy.com/fr/fine-parser/enterprise/concepts/scaling.md#unit-size-and-leases). |
| Les tâches échouent avec l’erreur `finalize-failed` | Vérifiez que les unités de traitement disposent des droits d’écriture sur le volume de sortie. |
| Les requêtes échouent avec le code `413` | Augmentez `ingest.maxUploadSize`, puis définissez `ingest.scratchSize` à environ le double de cette valeur. |
| Les pods d’ingestion sont évincés pendant les téléversements | Augmentez `ingest.scratchSize` ou réduisez `ingest.maxUploadSize`. |
| `GET /jobs/{jobId}` renvoie `404` pour une tâche connue | Son statut a expiré une fois le délai `orchestrator.jobRetentionSeconds` écoulé. Les résultats restent disponibles sur le volume de sortie. |

## Mises à niveau

| Symptôme | Solution |
| - | - |
| Conflit sur `.spec.replicas` | Relancez la même commande `helm upgrade`. |
| Une mise à niveau échoue sur une StorageClass, un PersistentVolume ou un PersistentVolumeClaim | Cette modification nécessite une réinstallation. Voir [Modifications nécessitant une réinstallation](https://docs.abbyy.com/fr/fine-parser/enterprise/best-practices/upgrades.md#changes-that-need-a-reinstall). |