What causes "A worker process lost access to an input file" in ocrmypdf/OCRmyPDF?

Free space on the filesystem holding TMPDIR (often /tmp on tmpfs) and on the output volume; retry the job.

ocrmypdf/OCRmyPDF · critical · InputFileError

A worker process lost access to an input file

Error message

A worker process lost access to an input file

What it means

In the multiprocessing executor, a SIGBUS signal handler installed in each worker raises InputFileError with this message. SIGBUS on Linux typically means a file backing the processing (input PDF or a temp/ramfs file) was truncated, deleted, or its filesystem ran out of space while a worker had it mapped or open.

Source

Thrown at src/ocrmypdf/builtin_plugins/concurrency.py:68

    https://docs.python.org/3/howto/logging-cookbook.html#logging-to-a-single-file-from-multiple-processes
    """
    while True:
        try:
            record = q.get()
            if record is None:
                break
            logger = logging.getLogger(record.name)
            logger.handle(record)
        except Exception:  # pylint: disable=broad-except
            import traceback  # pylint: disable=import-outside-toplevel

            print("Logging problem", file=sys.stderr)
            traceback.print_exc(file=sys.stderr)


def process_sigbus(*args):
    """Handle SIGBUS signal at the worker level."""
    raise InputFileError("A worker process lost access to an input file")


def process_init(q: Queue, user_init: UserInit, loglevel) -> None:
    """Initialize a process pool worker."""
    # Ignore SIGINT (our parent process will kill us gracefully)
    signal.signal(signal.SIGINT, signal.SIG_IGN)

    # Install SIGBUS handler (so our parent process can abort somewhat gracefully)
    with suppress(AttributeError):  # Windows and Cygwin do not have SIGBUS
        # Windows and Cygwin do not have pthread_sigmask or SIGBUS
        signal.signal(signal.SIGBUS, process_sigbus)

    # Remove any log handlers inherited from the parent process
    root = logging.getLogger()
    remove_all_log_handlers(root)

    # Set up our single log handler to forward messages to the parent
    root.setLevel(loglevel)

View on GitHub (pinned to 5074a0b0e1)

Solutions

Free space on the filesystem holding TMPDIR (often /tmp on tmpfs) and on the output volume; retry the job.
Ensure the input PDF is not modified/deleted while the job runs; keep it on local stable storage rather than a flaky network mount.
Set TMPDIR to a directory on a disk-backed filesystem with ample space; reduce --jobs if memory pressure is involved.

Defensive patterns

Strategy: try-catch

Validate before calling

import shutil, os
assert shutil.disk_usage(os.environ.get('TMPDIR','/tmp')).free > 1_000_000_000, 'low space in TMPDIR'

Try / catch

from ocrmypdf.exceptions import InputFileError
try:
    ocr(in_pdf, out_pdf)
except InputFileError as e:
    # worker lost access: free space / stabilize input, then retry once
    cleanup_and_retry()

Prevention

Monitor free space on TMPDIR and output filesystem during long jobs.
Never delete or rewrite the input PDF while a job is running.
Prefer disk-backed TMPDIR over small tmpfs for large jobs.

When it happens

Trigger: Running ocrmypdf with the standard process-pool concurrency when the input file (or a temp file under /tmp or TMPDIR) is removed/truncated mid-run, or disk/tmpfs space is exhausted.

Common situations: Cleaning tmp directories from another process during a long job, Docker containers with a small tmpfs, network filesystems dropping out, or oversubscribed RAM when tmpfs is used.

Related errors

AI-assisted analysis of ocrmypdf/OCRmyPDF@5074a0b0e1 (2026-08-27). Data as JSON: /api/errors/18ce961de6daeca1. Report an issue: GitHub.