Windows Console Encoding (GBK / UTF-8 Mismatch)#

Overview#

On Windows systems configured with a Chinese locale, the default console code page is GBK (CP936). MinerU has no code that reconfigures this at startup, so any Unicode character that falls outside GBK's repertoire — such as © (\xa9) — triggers a UnicodeEncodeError when Python tries to write it to stdout or stderr.

The canonical symptom is a parse failure returned as an API error 1:

'gbk' codec can't encode character '\xa9' in position 593: illegal multibyte sequence

Root Cause#

The immediate source of bare print() calls that bypass encoding-aware output is in mineru/cli/fast_api.py — specifically the two startup banner lines in the main() function:

print(f"Start MinerU FastAPI Service: http://{host}:{port}")
print(f"API documentation: http://{host}:{port}/docs")

These calls write to sys.stdout with no encoding argument. On a GBK console, if the string or any upstream output contains non-GBK characters, Python raises UnicodeEncodeError 2.

The logger in the same file is set up correctly — it routes to sys.stderr via loguru — but the two print() calls remain unguarded 3:

log_level = os.getenv("MINERU_LOG_LEVEL", "INFO").upper()
logger.remove()
logger.add(sys.stderr, level=log_level)

No CLI entry point (including fast_api.py, common.py, or gradio_app.py) calls sys.stdout.reconfigure(encoding='utf-8') or sets PYTHONUTF8 programmatically. 4 5 6

Workarounds (User-Side)#

Apply one of the following before launching MinerU 7:

Then run mineru server start (or the relevant CLI command) as usual.

Recommended Fix (Code-Side)#

Two approaches are tracked in the issue 8:

1. Replace print() with logger — loguru is already imported and configured; swapping the two startup banner print() calls in fast_api.py lines 1449–1450 for logger.info(...) would eliminate the unguarded stdout writes.
2. Reconfigure stdout at the CLI entry point — add sys.stdout.reconfigure(encoding='utf-8') (Python ≥ 3.7) or check sys.platform == 'win32' and set the encoding explicitly before any output occurs.

This issue is tagged [NEXT] in the upstream tracker, meaning it is queued for an upcoming release but not yet patched 9.

Relevant Files#