Tencent/WeKnora · error

MinerU API status %d: %s

Error message

MinerU API status %d: %s

What it means

callFileParse in the MinerU converter performs an HTTP request to the self-hosted or cloud MinerU document-parsing service. When the service responds with any HTTP status other than 200, the converter aborts and wraps the status code plus the raw response body into this error so the caller can see exactly what the MinerU API rejected. It indicates the request reached MinerU but was refused or failed server-side.

Source

Thrown at internal/infrastructure/docparser/mineru_converter.go:254

	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, c.endpoint+"/file_parse", &body)
	if err != nil {
		return "", nil, fmt.Errorf("create request: %w", err)
	}
	httpReq.Header.Set("Content-Type", writer.FormDataContentType())

	client := utils.NewSSRFSafeHTTPClient(utils.SSRFSafeHTTPClientConfig{
		Timeout:      mineruTimeout,
		MaxRedirects: 5,
	})
	resp, err := client.Do(httpReq)
	if err != nil {
		return "", nil, fmt.Errorf("HTTP request: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		respBody, _ := io.ReadAll(resp.Body)
		return "", nil, fmt.Errorf("MinerU API status %d: %s", resp.StatusCode, string(respBody))
	}

	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		return "", nil, fmt.Errorf("read response body: %w", err)
	}

	// Dump raw response for debugging (truncate if too large)
	rawStr := string(respBody)
	if len(rawStr) > 4000 {
		logger.Infof(context.Background(), "[MinerU] Raw response (truncated to 4000 chars): %s ...", rawStr[:4000])
	} else {
		logger.Infof(context.Background(), "[MinerU] Raw response: %s", rawStr)
	}

	// Also pretty-print the top-level structure (without large base64 blobs)
	var rawMap map[string]interface{}
	if err := json.Unmarshal(respBody, &rawMap); err == nil {

View on GitHub (pinned to 988cbb0330)

Solutions

1. Read the status and body in the error: the response body usually contains MinerU's own JSON error message pinpointing the cause
2. If 401/403, verify the MinerU API token/credentials configured for the converter and rotate if expired
3. If 404, check the MinerU base URL and endpoint path against your deployed MinerU version
4. If 400/413, confirm the file type/size is supported and within MinerU's limits
5. If 429, add backoff/retry with rate limiting; if 5xx, check MinerU service health and logs

Example fix

// before
cfg := MinerUConfig{BaseURL: "http://mineru:8000/v1/parse"}
// after (align path with deployed MinerU version and valid token)
cfg := MinerUConfig{BaseURL: os.Getenv("MINERU_BASE_URL") + "/file_parse", Token: os.Getenv("MINERU_API_TOKEN")}

if resp.StatusCode != http.StatusOK {
    body, _ := io.ReadAll(resp.Body)
    switch {
    case resp.StatusCode == 401 || resp.StatusCode == 403:
        // refresh/verify MinerU credentials before retrying
    case resp.StatusCode == 429:
        // back off and retry later
    }
}

func isMinerUStatusError(err error) (int, string, bool) {
    var e *MinerUStatusError
    if errors.As(err, &e) { return e.StatusCode, e.Body, true }
    return 0, "", false
}

md, imgs, err := reader.Read(ctx, req)
if err != nil {
    if code, body, ok := isMinerUStatusError(err); ok && (code == 429 || code >= 500) {
        // retry with backoff
    }
    return fmt.Errorf("parse failed: %w", err)
}

When it happens

Trigger: MinerU returns 400 (malformed multipart/file), 401/403 (bad or expired token), 404 (wrong endpoint path), 413 (file too large), 429 (rate limit), or 5xx (server-side parse failure) during callFileParse, which is invoked from Read.

Common situations: Wrong MINERU endpoint URL or API version path; invalid or rotated MinerU API token; uploading a file type or size MinerU rejects; MinerU pod OOM/crashing under load behind a 502/503 from the ingress.

Related errors

• read response body: %w
• http read status %d: %s
• http decode read response: %w
• MinerU file_parse: %w
• create request: %w

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/4d775705cd89f8f8. Report an issue: GitHub.