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

# Troubleshooting

Start with:

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

## Health checks

Every component serves `GET /healthz` on port 8080 as its readiness probe. A ready pod answers `{"status":"ok"}`. An unready pod answers `503` with `status` and the reason in `error`, and stays running rather than restarting.

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

| Component | Unready while |
| - | - |
| Orchestrator | It has not yet read the worker Deployment through the Kubernetes API. |
| Ingest | It cannot use a volume, or has not yet reached the orchestrator. |
| Worker | The engine is starting, billing is not yet confirmed, or the default profile was refused. |

## Installation

### A claim stays Pending

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

For the in-process claim: the EFS CSI driver is missing, its controller lacks `AmazonEFSCSIDriverPolicy`, or `fileSystemId` is wrong. For `mnesia-fineparser-orchestrator-0`: the cluster has no default StorageClass, or its driver is missing.

### Pods are stuck in ContainerCreating

`kubectl describe pod` shows the cause.

* EFS mounts time out: no mount target in the node's Availability Zone, or TCP 2049 is blocked.
* S3 mounts fail: wrong bucket or region, or the Mountpoint driver's role cannot access the bucket. `No signing credentials available` means the role's trust policy does not match the cluster's OIDC provider.

### Pods fail with exec format error

The pod is on an `arm64` node. See [Run on amd64](https://docs.abbyy.com/fine-parser/enterprise/best-practices/scheduling.md#run-on-amd64).

## Workers

### No workers start

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

If the Deployment wants workers but they are Pending, the cluster has no room: check that your node autoscaler can add `amd64` nodes matching `worker.nodeSelector` and `worker.tolerations`. With `worker.prepull` enabled, also check the pre-pull DaemonSet is running on the new nodes.

### Workers exit at startup

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

The line `billing refused this worker, exiting:` gives the reason.

| Reason | Fix |
| - | - |
| `AWS_ROLE_ARN is unset` or `AWS_REGION is unset` | The service account has no `eks.amazonaws.com/role-arn` annotation. See [IAM and billing](https://docs.abbyy.com/fine-parser/enterprise/aws/iam-and-billing.md). |
| `AccessDenied` | Attach `AWSMarketplaceMeteringRegisterUsage` to the role. |
| An STS error | The role's trust policy does not match the cluster, namespace, or service account. |
| `CustomerNotEntitled` | The account has no active subscription. |
| A certificate error | A proxy is inspecting TLS to `*.amazonaws.com`. Exempt it. |

`billing: RegisterUsage failed, retrying` is a transient error the worker retries.

### Workers are unready

FineReader Engine refused the default profile. The worker's log and `/healthz` give the reason. Fix `worker.predefinedProfile` or `worker.userProfile`, upgrade, and restart the workers.

### Workers restart with exit code 2

A worker that fails five units in a row restarts. Check the failed jobs' `failure.message`. If every document fails, look at the volumes or the profile.

## Jobs

| Symptom | Fix |
| - | - |
| Jobs fail with `timed-out` | Raise `orchestrator.workLeaseSeconds` or lower `ingest.pageSplitThreshold`. See [Unit size and leases](https://docs.abbyy.com/fine-parser/enterprise/concepts/scaling.md#unit-size-and-leases). |
| Jobs fail with `finalize-failed` | Check the workers can write to the output volume. |
| Requests fail with `413` | Raise `ingest.maxUploadSize`, and `ingest.scratchSize` to about twice that. |
| Ingest pods are evicted during uploads | Raise `ingest.scratchSize`, or lower `ingest.maxUploadSize`. |
| `GET /jobs/{jobId}` returns `404` for a known job | Its status expired after `orchestrator.jobRetentionSeconds`. The results are still on the output volume. |

## Upgrades

| Symptom | Fix |
| - | - |
| Conflict on `.spec.replicas` | Run the same `helm upgrade` again. |
| An upgrade fails on a StorageClass, PersistentVolume, or claim | The change needs a reinstall. See [Changes that need a reinstall](https://docs.abbyy.com/fine-parser/enterprise/best-practices/upgrades.md#changes-that-need-a-reinstall). |