open-webui/open-webui · critical · HTTPException

Error calling MinerU Local API: {str(e)}

Error message

Error calling MinerU Local API: {str(e)}

What it means

Catch-all HTTP 500 for any non-HTTPError, non-Timeout exception while calling the Local API. Most often this is requests.ConnectionError (service unreachable, DNS failure, refused connection) because the loader has no dedicated except clause for it, so connection problems surface as a generic 500.

Source

Thrown at backend/open_webui/retrieval/loaders/mineru.py:128

        except FileNotFoundError:
            raise HTTPException(status.HTTP_404_NOT_FOUND, detail=f'File not found: {self.file_path}')
        except requests.Timeout:
            raise HTTPException(
                status.HTTP_504_GATEWAY_TIMEOUT,
                detail='MinerU Local API request timed out',
            )
        except requests.HTTPError as e:
            error_detail = f'MinerU Local API request failed: {e}'
            if e.response is not None:
                try:
                    error_data = e.response.json()
                    error_detail += f' - {error_data}'
                except Exception:
                    error_detail += f' - {e.response.text}'
            raise HTTPException(status.HTTP_400_BAD_REQUEST, detail=error_detail)
        except Exception as e:
            raise HTTPException(
                status.HTTP_500_INTERNAL_SERVER_ERROR,
                detail=f'Error calling MinerU Local API: {str(e)}',
            )

        # Parse response
        try:
            result = response.json()
        except ValueError as e:
            raise HTTPException(
                status.HTTP_502_BAD_GATEWAY,
                detail=f'Invalid JSON response from MinerU Local API: {e}',
            )

        # Extract markdown content from response
        if 'results' not in result:
            raise HTTPException(
                status.HTTP_502_BAD_GATEWAY,
                detail="MinerU Local API response missing 'results' field",

View on GitHub (pinned to 01f4282f1f)

Solutions

  1. Confirm the service is up: curl {api_url}/docs or the health endpoint from the same host/network namespace
  2. Fix api_url to the actually reachable address (e.g. http://host.docker.internal:8000 or the service name in docker-compose)
  3. Check MinerU container logs for a crash/OOM and restart it
  4. If remote, verify DNS resolution and firewall rules on the port
  5. Add a preflight connectivity check before invoking load() (see defense)

Example fix

// before
loader = MinerULoader(file_path=p, api_mode='local', api_url='http://localhost:8000')

// after
# from inside another container, reach the service by name
loader = MinerULoader(file_path=p, api_mode='local', api_url='http://mineru:8000')
Defensive patterns

Strategy: validation

Validate before calling

import requests, socket
socket.gethostbyname(urlparse(api_url).hostname)  # fails fast on DNS
r = requests.get(f'{api_url}/docs', timeout=5)
assert r.status_code == 200, f'MinerU Local API not reachable at {api_url}'

Try / catch

try:
    docs = loader.load()
except HTTPException as e:
    if e.status_code == 500 and 'Error calling MinerU Local API' in e.detail:
        # detail will contain 'ConnectionError' when the service is down
        raise RuntimeError(f'MinerU unreachable: {e.detail}') from e
    raise

Prevention

When it happens

Trigger: MinerU container/process not running; wrong api_url host or port (default http://localhost:8000); DNS resolution failure for a remote MinerU host; TLS certificate error on an https api_url.

Common situations: Docker networking mismatch (container localhost vs host gateway); MinerU crashed from OOM during a previous parse; api_url typo or stale port after redeploying the service; firewall blocking egress to a remote MinerU instance.

Related errors

AI-assisted analysis of open-webui/open-webui@01f4282f1f (2026-08-14). Data as JSON: /api/errors/045c5185ef993a4f. Report an issue: GitHub.