Tencent/WeKnora · error

anydoc scanned-PDF fallback returned no result for %q

Error message

anydoc scanned-PDF fallback returned no result for %q

What it means

In the anydoc document reader, when the primary parser detects a scanned PDF it re-reads the file with a fallback (built-in OCR) engine. This error is returned when that fallback reports success but yields a nil result, i.e. no readable content could be produced for the scanned PDF.

Source

Thrown at internal/infrastructure/docparser/anydoc_reader.go:100

}

func (r *AnydocReader) readScannedPDF(ctx context.Context, req *types.ReadRequest, convertErr error) (*types.ReadResult, error) {
	if !r.canFallback() {
		if convertErr != nil {
			return nil, fmt.Errorf("anydoc conversion failed for %q: %w", req.FileName, convertErr)
		}
		return nil, fmt.Errorf("anydoc conversion failed for %q: PDF has no extractable text; OCR is required", req.FileName)
	}

	logger.Infof(ctx, "[anydoc] %q has no text layer, falling back to builtin for scanned-PDF OCR", req.FileName)
	fallbackReq := *req
	fallbackReq.ParserEngine = BuiltinEngineName
	result, err := r.fallback.Read(ctx, &fallbackReq)
	if err != nil {
		return nil, fmt.Errorf("anydoc scanned-PDF fallback failed for %q: %w", req.FileName, err)
	}
	if result == nil {
		return nil, fmt.Errorf("anydoc scanned-PDF fallback returned no result for %q", req.FileName)
	}
	if result.Metadata == nil {
		result.Metadata = map[string]string{}
	}
	if result.Metadata["parser"] == "" {
		result.Metadata["parser"] = BuiltinEngineName
	}
	result.Metadata["anydoc_fallback"] = "scanned_pdf"
	if result.Metadata["image_source_type"] == "" {
		result.Metadata["image_source_type"] = "scanned_pdf"
	}
	return result, nil
}

func (r *AnydocReader) canFallback() bool {
	if r.fallback == nil {
		return false
	}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Open the PDF and confirm it actually contains scannable content; a blank/corrupt file must be fixed at the source.
2. Verify the fallback (built-in OCR) engine is correctly configured and healthy for this tenant.
3. Inspect result construction in the fallback reader — a nil result with nil error is a bug; log req.FileName and the primary engine's scan detection metadata.
4. Handle the error upstream by informing the user the scanned PDF could not be converted.

Example fix

// before
result, err := r.fallback.Read(ctx, &fallbackReq)
if err != nil { return nil, ... }
// after
result, err := r.fallback.Read(ctx, &fallbackReq)
if err != nil || result == nil {
    return nil, fmt.Errorf("scanned-PDF fallback produced no content for %q", req.FileName)
}

res, err := reader.Read(ctx, req)
if err != nil && strings.Contains(err.Error(), "scanned-PDF fallback") {
    // notify user the scanned PDF could not be converted; inspect fallback engine config
}

When it happens

Trigger: Calling Read on a scanned (image-only) PDF where the primary engine flags it as scanned and r.fallback.Read returns (nil, nil) — a nil-result-without-error condition in the fallback reader.

Common situations: Blank or corrupted scanned PDFs; OCR engine installed but producing empty output; misconfigured fallback reader in the registry; PDFs whose pages are pure images with no extractable text even after OCR.

Related errors

• csv conversion failed: %w
• json conversion failed: %w
• unsupported simple format: %s
• parser engine %q is unavailable: %s
• gRPC ReadStream returned no metadata frame

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