{"record":{"id":"9568e13ca05ca979","repo":"Tencent/WeKnora","slug":"mineru-file-parse-w","errorCode":null,"errorMessage":"MinerU file_parse: %w","messagePattern":"MinerU file_parse: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/infrastructure/docparser/mineru_converter.go","lineNumber":85,"sourceCode":"\tif err := validateMinerUOutboundURL(c.endpoint); err != nil {\n\t\treturn &types.ReadResult{Error: err.Error()}, nil\n\t}\n\tif c.vlmServerURL != \"\" {\n\t\tif err := validateMinerUOutboundURL(c.vlmServerURL); err != nil {\n\t\t\treturn &types.ReadResult{Error: err.Error()}, nil\n\t\t}\n\t}\n\n\tcontent := req.FileContent\n\tif len(content) == 0 {\n\t\treturn &types.ReadResult{Error: \"no file content provided\"}, nil\n\t}\n\n\tlogger.Infof(context.Background(), \"[MinerU] Parsing file=%s size=%d via %s\", req.FileName, len(content), c.endpoint)\n\n\tmdContent, imagesB64, err := c.callFileParse(ctx, content, req.FileName, req.FileType)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"MinerU file_parse: %w\", err)\n\t}\n\n\t// MinerU already returns markdown with embedded HTML blocks (e.g. <table>, <details>).\n\t// Re-running the whole document through html-to-markdown corrupts valid markdown\n\t// by escaping headings and image syntax. Only apply narrow compatibility fixes.\n\tmdContent = normalizeMinerUMarkdown(mdContent)\n\n\t// Process images: decode base64, build ImageRef list, replace refs in markdown\n\timageRefs, mdContent := c.processImages(mdContent, imagesB64)\n\n\tmdContent, imageRefs = ensureOriginalImageRef(req, mdContent, imageRefs)\n\n\tlogger.Infof(context.Background(), \"[MinerU] Parsed successfully, markdown=%d chars, images=%d\", len(mdContent), len(imageRefs))\n\n\treturn &types.ReadResult{\n\t\tMarkdownContent: mdContent,\n\t\tImageRefs:       imageRefs,\n\t}, nil","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/infrastructure/docparser/mineru_converter.go#L67-L103","documentation":"Public entry point MinerUConverter.Read wraps every failure from callFileParse (the synchronous /file_parse API call) with this message. Any transport, request-construction, or response-decoding failure from the MinerU file parsing endpoint surfaces as 'MinerU file_parse: <cause>'. Inspect the wrapped cause to identify the real problem.","triggerScenarios":"Any error returned by callFileParse(ctx, content, req.FileName, req.FileType): bad multipart construction, HTTP failure, non-200 status, or unparseable response body.","commonSituations":"MinerU endpoint unreachable or misconfigured (wrong c.endpoint base URL); server returned 4xx/5xx (see companion 'MinerU API status %d' error); response JSON shape changed between MinerU versions.","solutions":["Unwrap the error (errors.Unwrap / %v of the cause) to see which inner step failed.","Verify c.endpoint is correct and reachable (curl $ENDPOINT/file_parse/health if available).","Check MinerU server logs for the corresponding request to see the server-side failure.","Confirm the file content and FileType are valid for MinerU (supported formats: pdf, images, etc.)."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"doc, err := conv.Read(ctx, req)\nif err != nil {\n    var transient bool\n    if strings.Contains(err.Error(), \"HTTP request\") || strings.Contains(err.Error(), \"read zip body\") {\n        transient = true // safe to retry\n    }\n    log.Printf(\"mineru parse failed (retryable=%v): %v\", transient, err)\n    if transient {\n        doc, err = conv.Read(ctx, req)\n    }\n}","preventionTips":["Always unwrap and classify the cause before deciding to retry","Health-check the MinerU endpoint at service startup","Wrap synchronous parse calls with a timeout budget and queue for async reprocessing","Alert on spikes of this wrapper error"],"tags":["http","mineru","wrapper","document-parsing"],"backgroundTag":"upstream-api-call-failed","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}