docling-project/docling · warning · ValueError

File does not exist or it is not readable.

Error message

File does not exist or it is not readable.

What it means

Local fetch was allowed and base_path given, but the resolved path either does not exist as a file or the process lacks read permission (os.path.isfile + os.access checks both failed). Raised as ValueError; the loader refuses to guess between missing and unreadable.

Source

Thrown at docling/backend/utils/image_resource_loader.py:275

            return decoded_data

        if not self.enable_local_fetch:
            raise OperationNotAllowed(
                "Fetching local resources is only allowed when set explicitly. "
                "Set options.enable_local_fetch=True."
            )

        # Require base_path for directory confinement (validation done in resolve_relative_path)
        if not base_path:
            raise OperationNotAllowed(
                f"Local file access requires base_path for directory confinement: '{src_loc}'"
            )

        if os.path.isfile(src_loc) and os.access(src_loc, os.R_OK):
            with open(src_loc, "rb") as f:
                return f.read()
        else:
            raise ValueError("File does not exist or it is not readable.")

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Verify the image exists next to the source document and the src attribute resolves to it (check spelling, case, subdirectory).
2. Fix permissions: chmod the file readable by the running user/group.
3. Re-package the document with its assets so relative references resolve under base_path.
4. Remove the dangling reference from the input if the image is optional.

Example fix

# before
# index.html references <img src="images/Chart1.PNG"> but on disk it is chart1.png

# after
# rename the asset to match the reference exactly (case-sensitive FS)
$ mv images/chart1.png images/Chart1.PNG

import os

def local_image_readable(abs_path: str) -> bool:
    return os.path.isfile(abs_path) and os.access(abs_path, os.R_OK)

try:
    data = loader.load_image_data(src, base_path)
except ValueError as e:
    if "not exist" in str(e) or "not readable" in str(e):
        logger.warning("missing/unreadable image %s; continuing without it", src)
    else:
        raise

When it happens

Trigger: Document references a local image path that does not exist (broken relative path, wrong casing on case-sensitive filesystems, image not shipped with the document) or a file the process cannot read (permission bits, root-squashed mounts).

Common situations: Copying an HTML file without its _files/ asset folder; extracting archives that drop images; paths with spaces or URL-encoded characters; files owned by another user in containers.

Related errors

• Absolute paths are not allowed with local base_path: '{loc}'
• Path traversal blocked: '{loc}' resolves outside base direct
• Fetching local resources is only allowed when set explicitly
• Local file access requires base_path for directory confineme
• URL must contain a valid hostname

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/278e210b67ae5904. Report an issue: GitHub.