---
title: BioBERT troubleshooting
description: Why a BioBERT job returned no entities or the wrong types — thresholds, segment boundaries, PDF artifacts. BioBERT is deprecated and chat cannot call it.
---

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.

> **Not available in chat**

> BioBERT is deprecated on the platform and not registered with the orchestrator, so chat cannot call it. A current LLM performs BioBERT's entity extraction and relevance ranking natively over text retrieved with [PubMed](/docs/pubmed); for curated identifiers an LLM must not invent (NCBI Gene IDs, MeSH terms), use PubTator3. Existing BioBERT job results remain viewable.

## 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

| Code | Meaning | Solution |
|------|---------|----------|
| `INVALID_INPUT` | Malformed input file | Check file format and encoding |
| `TOKEN_LIMIT_EXCEEDED` | Single document too long | Pre-segment before submission |
| `UNSUPPORTED_TASK` | Invalid task type | Use `ner`, `re`, or `qa` |
| `MODEL_TIMEOUT` | Processing exceeded limits | Reduce batch size |
| `QUOTA_EXCEEDED` | Daily limit reached | Wait for reset or upgrade tier |

## 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