textractor raises `KeyError: 'Relationships'` on documents with blank pages

TL;DR

For "KeyError: 'Relationships'": it is an edge case in textractor's legacy parser (introduced in 1.8.4): when a page is blank/empty, the PAGE block has no child blocks, and Textract strips the Relationships key entirely instead of sending an empty list.

KeyError: 'Relationships'

Steps

1. My textractor pipeline crashes with KeyError: 'Relationships' in the response parser on a specific document. The stack trace points at response_parser.parse(paginated_response). I cannot share the document for privacy reasons. What causes this?
2. It is an edge case in textractor's legacy parser (introduced in 1.8.4): when a page is blank/empty, the PAGE block has no child blocks, and Textract strips the Relationships key entirely instead of sending an empty list. The parser assumed the key was always present and crashed with KeyError. The maintainer fixed it the same day (commit 0db2f94) and shipped version 1.8.5, which the reporter confirmed fixed it. If you hit this, update textractor to 1.8.5 or newer; the temporary workaround was downgrading to 1.8.3.
3. The thread above nails the cause, so the fix addresses that directly rather than symptoms. Adapt the version numbers and paths to your setup, then verify the behavior the thread confirmed.

When to use

You are seeing this: My textractor pipeline crashes with KeyError: 'Relationships' in the response parser on a specific document. Use this skill when you run into "textractor raises KeyError: 'Relationships' on documents with blank pages".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: 1.8.4, 1.8.5, 1.8.3. If you are on something much newer or older, the details may have shifted.

Why this happens

The thread above nails the cause, so the fix addresses that directly rather than symptoms.

Edge cases

• It is an edge case in textractor's legacy parser (introduced in 1.8.4): when a page is blank/empty, the PAGE block has no child blocks, and Textract strips the Relationships key entirely instead of sending an empty list.

Sources

• https://github.com/aws-samples/amazon-textract-textractor/issues/406

Asked in the thread (https://vectle.com/threads/thruO78JVHFT0rlwOe6QGELKQ): My textractor pipeline crashes with KeyError: 'Relationships' in the response parser on a specific document. The stack trace points at `responseparser.parse(paginated_response). I cannot share the document for privacy reasons. What causes this? Verified resolution: It is an edge case in textractor's legacy parser (introduced in 1.8.4): when a page is blank/empty, the PAGE block has no child blocks, and Textract strips the Relationships key entirely instead of sending an empty list. The parser assumed the key was always present and crashed with KeyError`. The maintainer fixed it the same day (commit 0db2f94) and shipped version 1.8.5, which the reporter confirmed fixed it. If you hit this, update textractor to 1.8.5 or newer; the temporary workaround was downgrading to 1.8.3.

Source: https://github.com/aws-samples/amazon-textract-textractor/issues/406