docling-project/docling · error · ValueError

Invalid base_path format: '{base_path}'

Error message

Invalid base_path format: '{base_path}'

What it means

ValueError raised in resolve_relative_path when the location is relative but base_path is neither a remote URL (is_remote_url) nor a local path (is_local_path). The resolver cannot decide how to join the reference, so it refuses rather than guessing.

Source

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

            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(
        self, src_url: str, base_path: Optional[str]
    ) -> Optional[ImageRef]:
        try:
            img_data = self.load_image_data(src_url, base_path)
            if img_data:
                img = Image.open(BytesIO(img_data))
                return ImageRef.from_pil(img, dpi=int(img.info.get("dpi", (72,))[0]))
        except (
            requests.HTTPError,
            ValidationError,
            UnidentifiedImageError,
            OperationNotAllowed,
            TypeError,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pass a well-formed base: an http(s) URL or a local filesystem path string ending in the document filename.
2. Validate base_path before conversion (must start with http://, https://, file:/, or be an existing local path).
3. Omit base_path (None) only when all image refs are absolute.

Example fix

# before
loader.resolve_relative_path('img.png', 'example.com/docs/page')  # ValueError

# after
loader.resolve_relative_path('img.png', 'https://example.com/docs/page')

def valid_base(bp: str | None) -> bool:
    if bp is None:
        return True
    return bp.startswith(('http://', 'https://', 'file:')) or Path(bp).exists()
assert valid_base(base_path), f'bad base_path: {base_path}'

from pathlib import Path
def is_usable_base(bp: object) -> bool:
    return bp is None or (isinstance(bp, str) and (bp.startswith(('http://', 'https://')) or Path(bp).exists()))

try:
    loc = loader.resolve_relative_path(src, base)
except ValueError as e:
    if 'Invalid base_path' in str(e):
        loc = loader.resolve_relative_path(src, str(document_dir / 'index.html'))
    else:
        raise

When it happens

Trigger: Passing a base_path like a bare fragment, malformed string, or unsupported scheme (e.g. 'ftp://x/', ':::') together with a relative image location; the two is_* checks both fail and the else branch raises.

Common situations: Programmatic callers constructing base_path from unvalidated user input or config values; documents whose retrieval URL was mangled upstream; passing a Path object where a string URL was expected in custom code.

Related errors

• Cannot convert Box Note with hash {self.document_hash}: no '
• Cannot convert doc with {self.document_hash} because the bac
• Archive exceeds maximum member count limit of {self.options.
• URL must contain a valid hostname
• Cannot resolve hostname: {hostname}

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