docling-project/docling · error · ArtifactDownloadError

Resource bundle references an image outside the bundle: {uri

Error message

Resource bundle references an image outside the bundle: {uri}

What it means

Raised as ArtifactDownloadError during _embed_referenced_images: the server-supplied document JSON references an image with a relative URI (e.g. '../../secret.png') that resolves outside the extraction directory. The zip-slip guard only validates ZIP members, so URIs inside the JSON get their own containment check before being opened with PIL. This blocks the document JSON from reading arbitrary local image files.

Source

Thrown at docling/service_client/client.py:1838

        and resolves relative ``Path`` URIs against the process working directory.
        Bundle artifacts are extracted into a temporary directory, so both
        picture and page image references must be resolved against ``base_dir``
        explicitly before being inlined.
        """

        base_resolved = base_dir.resolve()

        def embed(image_ref: ImageRef) -> ImageRef:
            uri = image_ref.uri
            if not isinstance(uri, Path) or uri.is_absolute():
                return image_ref
            resolved = (base_dir / uri).resolve()
            # Containment guard: the document JSON is server-supplied, so a
            # relative URI like ``../../secret.png`` must not escape the extract
            # dir and read arbitrary local image files. The zip-slip guard only
            # validates ZIP members, not the URIs the JSON references.
            if resolved != base_resolved and base_resolved not in resolved.parents:
                raise ArtifactDownloadError(
                    f"Resource bundle references an image outside the bundle: {uri}"
                )
            with PILImage.open(resolved) as pil_image:
                pil_image.load()
                return ImageRef.from_pil(pil_image.copy(), dpi=image_ref.dpi)

        for item, _level in document.iterate_items(with_groups=False):
            if isinstance(item, PictureItem) and item.image is not None:
                item.image = embed(item.image)
        for page in document.pages.values():
            if page.image is not None:
                page.image = embed(page.image)

    def _build_conversion_result_from_artifact_item(
        self,
        item: DocumentArtifactItem,
        document: DoclingDocument,
        descriptor: _SourceDescriptor,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Read the failure from the per-document ConversionResult; the document is reported as FAILURE
2. Verify the docling-serve instance is trusted and up to date
3. Avoid referenced-image mode for untrusted service endpoints

def is_artifact_download_error(exc: BaseException) -> bool:
    return isinstance(exc, ArtifactDownloadError)

if res.status == ConversionStatus.FAILURE:
    # containment violation on server-supplied URIs — do not whitelist, investigate
    log_security_event(res.errors)

When it happens

Trigger: Bundle-mode convert() where a PictureItem.image.uri or page image uri is a relative Path that escapes base_dir after resolution; absolute URIs are skipped (returned as-is), only escaping relative paths trigger it.

Common situations: Malicious or corrupted server response crafting traversal URIs; a server bug emitting workspace-relative paths instead of bundle-relative ones.

Related errors

• Resource bundle contains an unsafe path: {member!r}
• ZIP slip attempt: {info.filename}
• Path traversal blocked: '{loc}' resolves outside base direct
• ZIP slip attempt: {member.filename}
• Too many redirects while downloading artifact.

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