BioBERT troubleshooting

This page helps you diagnose why a BioBERT job returned no or misclassified entities, missing relationships, or poor answers — often traceable to non-biomedical content, confidence thresholds, text truncation at segment boundaries, or PDF extraction artifacts.

Common issues

No entities detected

Symptoms: Job completes but returns empty or minimal entity list

Possible causes and solutions:

• Non-biomedical content: BioBERT is trained on PubMed/PMC; general text may not contain recognizable entities. Verify text contains biomedical terminology.
• Confidence threshold too high: Lower the confidence_threshold parameter from 0.9 to 0.7 or 0.5 to capture more entities
• Wrong entity types selected: Ensure requested entity types match content (e.g., don't select only "gene" for a pharmacology paper)
• Text preprocessing issues: Check that text wasn't corrupted during upload; verify UTF-8 encoding
• Very short text: Single sentences may not provide enough context for reliable detection

Incorrect entity classification

Symptoms: Entities detected but assigned wrong types (e.g., drug classified as gene)

Possible causes and solutions:

• Domain ambiguity: Some terms have multiple meanings (e.g., "p53" as gene vs. protein). Review context and consider post-processing rules.
• Abbreviations without context: Unexpanded abbreviations may be misclassified. Expand abbreviations in preprocessing.
• Out-of-vocabulary terms: Novel or very rare terms may be misclassified. Consider lower confidence thresholds and manual review.
• Overlapping entity spans: When entities overlap, prioritize based on your use case

Text truncation

Symptoms: Entities at document boundaries missing or incomplete

Possible causes and solutions:

• Long documents: BioBERT automatically splits at 512 tokens with 64-token overlap. Entities spanning segment boundaries may be affected.
• Check segment boundaries: Review the segment_index field in output to identify boundary issues
• Pre-processing recommendation: Split at natural boundaries (paragraph breaks) before submission for cleaner results
• Overlap adjustment: Contact support if default overlap is insufficient for your use case

PDF extraction issues

Symptoms: Poor entity detection from PDF-derived text

Possible causes and solutions:

• Conversion artifacts: PDF-to-text conversion may introduce formatting issues. Try different PDF extraction tools (pdftotext, PyMuPDF).
• Scanned images: Scanned PDFs require OCR first. Use dedicated OCR tools before BioBERT processing.
• Layout issues: Multi-column layouts may cause text order problems. Review extracted text before submission.
• Headers/footers: Remove repeated headers, page numbers, and footers that add noise
• Tables and figures: Extract these separately; inline table text often causes entity detection issues

Relation extraction failures

Symptoms: RE task returns no relationships despite entities present

Possible causes and solutions:

• Entity distance: Entities must be in same or adjacent sentences for RE. Very distant entity pairs won't be linked.
• Unsupported relationship types: Verify the relationship type exists in the model's training data
• Missing entity recognition: RE depends on NER; check that both entities are correctly detected first
• Confidence filtering: Lower RE confidence threshold (default may be higher than NER)

Question answering issues

Symptoms: QA returns "no answer" or irrelevant answers

Possible causes and solutions:

• Answer not in context: QA can only extract answers present in provided text. Verify answer is explicitly stated.
• Question phrasing: Try rephrasing questions to match terminology in the text
• Context too long: Long context dilutes attention. Provide focused, relevant passages.
• Domain mismatch: Questions about non-biomedical topics will perform poorly

Quality checks

Validation approaches

• Known entity validation: Test against documents with manually annotated entities
• Cross-reference databases: Verify detected genes in NCBI Gene, diseases in MeSH, chemicals in PubChem
• Confidence calibration: For your domain, determine which confidence thresholds yield acceptable precision/recall

Review priorities

• Low-confidence predictions (<0.7): Manual review recommended
• Boundary cases: Entities at segment boundaries need extra attention
• Novel entities: Entities not in standard databases may be errors or genuine discoveries

If a job fails

Diagnostic steps

1. Check input encoding: Ensure files are UTF-8 encoded; non-UTF-8 characters cause parsing failures
2. Remove special formatting: Strip HTML tags, markdown, and complex formatting
3. Validate file format: Ensure CSV has proper headers; TXT is plain text
4. Check file size: Verify file is under 50MB limit
5. Split very large files: Break into multiple jobs if approaching limits
6. Review error message: Check job logs for specific error codes

Error codes

Escalation

If issues persist after troubleshooting:

1. Note the job ID from the job page
2. Export the first 10 problematic documents
3. Document the expected vs. actual behavior
4. Contact support with this information

Read next