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

# Solución de problemas

Empiece por lo siguiente:

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

## Comprobaciones de estado

Cada componente expone `GET /healthz` en el puerto 8080 como sonda de disponibilidad (readiness probe). Un pod listo responde `{"status":"ok"}`. Un pod que no está listo responde con `503`, con `status` y el motivo en `error`, y permanece en ejecución en lugar de reiniciarse.

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

| Componente | No está listo mientras |
| - | - |
| Orchestrator | Aún no ha leído el Deployment del worker a través de la API de Kubernetes. |
| Ingest | No puede usar un volumen o aún no ha conectado con el orchestrator. |
| Worker | El engine se está iniciando, la facturación aún no se ha confirmado o se ha rechazado el perfil predeterminado. |

## Instalación

### Un claim se queda en estado Pending

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

Para el claim in-process: no está instalado el controlador CSI de EFS, a su componente controller le falta `AmazonEFSCSIDriverPolicy` o el valor de `fileSystemId` es incorrecto. Para `mnesia-fineparser-orchestrator-0`: el clúster no tiene una StorageClass predeterminada o no está instalado su controlador.

### Los pods se quedan bloqueados en ContainerCreating

`kubectl describe pod` muestra la causa.

* Se agota el tiempo de espera de los montajes de EFS: no hay ningún destino de montaje en la zona de disponibilidad del nodo o el puerto TCP 2049 está bloqueado.
* Fallan los montajes de S3: el bucket o la región son incorrectos, o el rol del controlador Mountpoint no tiene acceso al bucket. `No signing credentials available` indica que la política de confianza del rol no coincide con el proveedor OIDC del clúster.

### Los pods fallan con un error de formato de exec

El pod se ejecuta en un nodo `arm64`. Consulte [Ejecutar en amd64](https://docs.abbyy.com/es/fine-parser/enterprise/best-practices/scheduling.md#run-on-amd64).

## Trabajadores

### No se inicia ningún trabajador

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

Si el Deployment requiere trabajadores pero estos permanecen en estado Pending, el clúster no tiene capacidad disponible: compruebe que el escalador automático de nodos pueda agregar nodos `amd64` que cumplan con `worker.nodeSelector` y `worker.tolerations`. Si `worker.prepull` está habilitado, compruebe también que el DaemonSet de descarga previa se esté ejecutando en los nodos nuevos.

### Los trabajadores se cierran al iniciar

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

La línea `billing refused this worker, exiting:` indica el motivo.

| Motivo | Solución |
| - | - |
| `AWS_ROLE_ARN is unset` o `AWS_REGION is unset` | La cuenta de servicio no tiene la anotación `eks.amazonaws.com/role-arn`. Consulte [IAM y facturación](https://docs.abbyy.com/es/fine-parser/enterprise/aws/iam-and-billing.md). |
| `AccessDenied` | Adjunte `AWSMarketplaceMeteringRegisterUsage` al rol. |
| Un error de STS | La política de confianza del rol no coincide con el clúster, el espacio de nombres o la cuenta de servicio. |
| `CustomerNotEntitled` | La cuenta no tiene ninguna suscripción activa. |
| Un error de certificado | Un proxy está inspeccionando el tráfico TLS hacia `*.amazonaws.com`. Exclúyalo de la inspección. |

`billing: RegisterUsage failed, retrying` es un error transitorio y el trabajador vuelve a intentar la operación.

### Los trabajadores no están listos

FineReader Engine rechazó el perfil predeterminado. El motivo figura en el registro del trabajador y en `/healthz`. Corrija `worker.predefinedProfile` o `worker.userProfile`, realice la actualización y reinicie los trabajadores.

### Los trabajadores se reinician con el código de salida 2

Un trabajador se reinicia cuando fallan cinco unidades seguidas. Revise el valor de `failure.message` de los trabajos fallidos. Si fallan todos los documentos, compruebe los volúmenes o el perfil.

## Trabajos

| Síntoma | Solución |
| - | - |
| Los trabajos fallan con `timed-out` | Aumente `orchestrator.workLeaseSeconds` o reduzca `ingest.pageSplitThreshold`. Consulte [Tamaño de unidad y concesiones](https://docs.abbyy.com/es/fine-parser/enterprise/concepts/scaling.md#unit-size-and-leases). |
| Los trabajos fallan con `finalize-failed` | Compruebe que los trabajadores tienen permisos de escritura en el volumen de salida. |
| Las solicitudes fallan con `413` | Aumente `ingest.maxUploadSize` y establezca `ingest.scratchSize` en aproximadamente el doble de ese valor. |
| Los pods de Ingest se desalojan durante las cargas | Aumente `ingest.scratchSize` o reduzca `ingest.maxUploadSize`. |
| `GET /jobs/{jobId}` devuelve `404` para un trabajo existente | Su estado caducó una vez transcurrido `orchestrator.jobRetentionSeconds`. Los resultados siguen disponibles en el volumen de salida. |

## Actualizaciones

| Síntoma | Solución |
| - | - |
| Conflicto en `.spec.replicas` | Vuelva a ejecutar el mismo `helm upgrade`. |
| Una actualización falla en un StorageClass, un PersistentVolume o un claim | El cambio requiere reinstalar. Consulte [Cambios que requieren reinstalar](https://docs.abbyy.com/es/fine-parser/enterprise/best-practices/upgrades.md#changes-that-need-a-reinstall). |