devops(ocr): improve startup error clarity for invalid CLAHE env vars #257

New Issue

marcel · 2026-04-17T15:20:10+02:00

marcel commented

2026-04-17 15:20:10 +02:00

Background

Deferred during PR #255 review cycle 1 (Tobias Wendt — DevOps review).

Concern

CLAHE_TILE_SIZE = int(os.environ.get("OCR_CLAHE_TILE_SIZE", "8")) crashes at service startup if the env var is set to a non-integer (e.g. "8x8"). The raw ValueError traceback from Python's int() call is cryptic — on-call engineers have to trace it back to find which env var is wrong.

"A ValueError traceback in the startup log can be confusing. A try/except with a clear error message would help on-call debugging." — @Tobias

Suggested fix

Extract a _parse_int_env(name, default) helper that wraps the int() call and raises a human-readable ValueError:

def _parse_int_env(name: str, default: str) -> int:
    raw = os.environ.get(name, default)
    try:
        return int(raw)
    except ValueError:
        raise ValueError(f"{name!r} must be an integer, got {raw!r}") from None

This is also testable directly, unlike the module-level assignment.

Why deferred

Non-blocking. The current fail-fast behaviour is correct; only the error message quality suffers. Implementing cleanly required the refactor above which was out of scope for the preprocessing pipeline PR.

Reference

PR: http://heim-nas:3005/marcel/familienarchiv/pulls/255

## Background Deferred during PR #255 review cycle 1 (Tobias Wendt — DevOps review). ## Concern `CLAHE_TILE_SIZE = int(os.environ.get("OCR_CLAHE_TILE_SIZE", "8"))` crashes at service startup if the env var is set to a non-integer (e.g. `"8x8"`). The raw `ValueError` traceback from Python's `int()` call is cryptic — on-call engineers have to trace it back to find which env var is wrong. > "A `ValueError` traceback in the startup log can be confusing. A try/except with a clear error message would help on-call debugging." — @Tobias ## Suggested fix Extract a `_parse_int_env(name, default)` helper that wraps the `int()` call and raises a human-readable `ValueError`: ```python def _parse_int_env(name: str, default: str) -> int: raw = os.environ.get(name, default) try: return int(raw) except ValueError: raise ValueError(f"{name!r} must be an integer, got {raw!r}") from None ``` This is also testable directly, unlike the module-level assignment. ## Why deferred Non-blocking. The current fail-fast behaviour is correct; only the error message quality suffers. Implementing cleanly required the refactor above which was out of scope for the preprocessing pipeline PR. ## Reference PR: http://heim-nas:3005/marcel/familienarchiv/pulls/255

marcel referenced this issue

2026-04-17 15:21:44 +02:00

feat(ocr): add image preprocessing pipeline to improve transcription quality on aged documents #255

marcel added the devops refactor labels 2026-04-17 15:33:31 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcel/familienarchiv#257