docling-project/docling · error · OperationNotAllowed

Fetching local or remote resources is only allowed when set

Error message

Fetching local or remote resources is only allowed when set explicitly. Set 'options.enable_local_fetch=True' or 'options.enable_remote_fetch=True'. Either one or the other needs to be enabled to load taxonomies.

What it means

The XBRL backend must load taxonomies to interpret an instance document, and Arelle will fetch them locally or remotely; both fetch modes default to False, so out of the box the backend raises OperationNotAllowed telling you to enable one. This is deliberate: taxonomy resolution touches the filesystem/network, which needs explicit opt-in.

Source

Thrown at docling/backend/xml/xbrl_backend.py:113

                "Please install it using `pip install 'docling-slim[format-xml-xbrl]'`"
            ) from _XBRL_IMPORT_ERROR

        super().__init__(in_doc, path_or_stream)
        self.options: XBRLBackendOptions = options
        self.model_xbrl: ModelXbrl | None = None
        self._kv_idx: int = 0
        self._cells: list[GraphCell] = []
        self._links: list[GraphLink] = []
        self._hierarchy_cell_ids: dict[str, int] = {}
        self._fact_cell_ids: dict[str, list[int]] = defaultdict(list)
        self._created_links: set[tuple[int, int]] = set()

        try:
            if (
                not self.options.enable_local_fetch
                and not self.options.enable_remote_fetch
            ):
                raise OperationNotAllowed(
                    "Fetching local or remote resources is only allowed when set"
                    " explicitly. Set 'options.enable_local_fetch=True' or"
                    " 'options.enable_remote_fetch=True'. Either one or the other"
                    " needs to be enabled to load taxonomies."
                )
            with TemporaryDirectory() as tmpdir:
                tmp_path: Path = Path(tmpdir)
                zip_paths: list[str] = []
                if self.options.taxonomy:
                    taxonomy: Path = self.options.taxonomy.resolve()
                    if not taxonomy.is_dir():
                        raise ValueError(
                            "The 'taxonomy' backend option must be a directory"
                        )
                    taxonomy_path = shutil.copytree(
                        taxonomy, tmp_path, dirs_exist_ok=True
                    )
                    zip_paths = [

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set options.enable_local_fetch=True if your taxonomy files are on disk (pass their directory via options.taxonomy).
2. Set options.enable_remote_fetch=True if taxonomies should be downloaded (e.g. standard SEC/EBA taxonomies); the backend then enables Arelle's web cache with a timeout.
3. For offline use, mirror the taxonomy locally and combine local fetch with options.taxonomy.
4. Configure via pipeline options: XBRLFormatOptions/XBRLBackendOptions passed in DocumentConverter format_options.

Example fix

# before
result = DocumentConverter().convert(Path("report.xbrl"))  # OperationNotAllowed

# after
from docling.datamodel.pipeline_options import XBRLBackendOptions
opts = XBRLBackendOptions(enable_remote_fetch=True)
result = DocumentConverter(
    format_options={InputFormat.XML_XBRL: opts}
).convert(Path("report.xbrl"))

def xbrl_fetch_configured(opts) -> bool:
    return opts.enable_local_fetch or opts.enable_remote_fetch  # False -> error [97] imminent

from docling.datamodel.settings import OperationNotAllowed

try:
    result = converter.convert(xbrl_path)
except OperationNotAllowed as e:
    if "enable_local_fetch" in str(e):
        raise ValueError("Configure XBRLBackendOptions enable_local_fetch or enable_remote_fetch") from e
    raise

When it happens

Trigger: Constructing XBRLBackend (or converting an XBRL file) with default XBRLBackendOptions where enable_local_fetch and enable_remote_fetch are both False — the check fires before any parsing, inside the try block in __init__.

Common situations: First XBRL conversion after installing the extra; security-hardened configs that disable fetch globally; air-gapped environments where remote fetch must not be attempted.

Related errors

• Fetching local resources is only allowed when set explicitly
• Local file access requires base_path for directory confineme
• The 'taxonomy' backend option must be a directory
• XBRL loaded with errors: {model.errors}
• Access to restricted IP address not allowed: {ip}

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