docling-project/docling · error · ValueError

Absolute paths are not allowed with local base_path: '{loc}'

Error message

Absolute paths are not allowed with local base_path: '{loc}'

What it means

ValueError raised in resolve_relative_path when base_path is a local path and the image location loc is absolute (e.g. '/etc/passwd.png' or 'C:\\x\\y.png'). With a local base, only relative references are permitted so a document cannot pull arbitrary files from the host filesystem.

Source

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

    def resolve_relative_path(self, loc: str, base_path: Optional[str]) -> str:
        loc = loc.strip()

        # Strip file:// prefix for validation as local path
        if loc.startswith(file_prefix := "file://"):
            loc = loc[len(file_prefix) :]

        abs_loc = loc

        if base_path:
            if loc.startswith("//"):
                abs_loc = "https:" + loc
            elif not loc.startswith(("http://", "https://", "data:", "#")):
                if ImageResourceLoader.is_remote_url(base_path):
                    abs_loc = urljoin(base_path, loc)
                elif ImageResourceLoader.is_local_path(base_path):
                    if ImageResourceLoader.is_absolute_path(loc):
                        raise ValueError(
                            f"Absolute paths are not allowed with local base_path: '{loc}'"
                        )

                    base_dir = Path(base_path).parent.resolve()
                    resolved_path = (base_dir / loc).resolve()

                    if not resolved_path.is_relative_to(base_dir):
                        raise ValueError(
                            f"Path traversal blocked: '{loc}' resolves outside base directory"
                        )
                    abs_loc = str(resolved_path)
                else:
                    raise ValueError(f"Invalid base_path format: '{base_path}'")

        _log.debug(f"Resolved location {loc} to {abs_loc}")
        return abs_loc

    def create_image_ref(

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Rewrite root-relative srcs to be relative to the document (strip the leading '/'), e.g. preprocess HTML to 'assets/img.png'.
2. If the files genuinely live at that path, pass a base_path whose directory contains them and use relative references.
3. Serve the document over http(s) with a proper base URL so '/' resolves via urljoin instead of the local-path branch.

Example fix

# before
<img src="/assets/logo.png">  # base_path='/data/page.html' -> ValueError

# after
<img src="assets/logo.png">  # resolves to /data/assets/logo.png

from pathlib import PurePosixPath, PureWindowsPath
def is_abs(p: str) -> bool:
    return PurePosixPath(p).is_absolute() or PureWindowsPath(p).is_absolute()
if base and is_local(base) and is_abs(src):
    src = src.lstrip('/')  # or rewrite to a relative reference

try:
    loc = loader.resolve_relative_path(src, base)
except ValueError as e:
    if 'Absolute paths' in str(e):
        loc = loader.resolve_relative_path(src.lstrip('/').replace('\\', '/'), base)
    else:
        raise

When it happens

Trigger: Converting an HTML/ODT file at /data/page.html whose <img src="/absolute/path/img.png"> (root-relative URL) is resolved with a local base_path; is_absolute_path(loc) is true and the guard fires.

Common situations: Website exports where image srcs start with '/', files authored on Windows with drive-letter paths, templates rendered with server-root paths.

Related errors

• Fetching local resources is only allowed when set explicitly
• Path traversal blocked: '{loc}' resolves outside base direct
• Resource size exceeds limit: {content_length} bytes
• Decoded image exceeds size limit of {self.max_image_data_bas
• Local file access requires base_path for directory confineme

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