Troubleshooting Guide

# Verify Python version (requires 3.11+, supports up to 3.14)
python --version

# If using wrong version, create conda environment
conda create -n lobster python=3.13
conda activate lobster

# Remove existing installation
pip uninstall lobster-ai

# Clean install with development dependencies
git clone https://github.com/the-omics-os/lobster.git
cd lobster
make clean-install

# Install with verbose output to see exact error
pip install -e . -v

# If conflicts occur, try constraint file
pip install -e . --constraint constraints.txt

# For conda users
conda env create -f environment.yml

# Verify API keys are set
echo $AWS_BEDROCK_ACCESS_KEY
echo $AWS_BEDROCK_SECRET_ACCESS_KEY

# Check .env file exists and is correctly formatted
cat .env

# Create or update .env file
cat > .env << EOF
AWS_BEDROCK_ACCESS_KEY=your-aws-access-key
AWS_BEDROCK_SECRET_ACCESS_KEY=your-aws-secret-key
NCBI_API_KEY=your-ncbi-api-key-optional
EOF

# Ensure no extra spaces or quotes

# Test with minimal example
python -c "
from lobster.config.settings import get_settings
settings = get_settings()
print('Settings loaded successfully')
"

# Install optional CLI enhancements
pip install prompt-toolkit

# Verify installation
python -c "import prompt_toolkit; print('Enhanced CLI available')"

# Test terminal capabilities
echo $TERM
python -c "
import sys
print(f'Terminal: {sys.stdout.isatty()}')
print(f'Colors: {hasattr(sys.stdout, \"isatty\")}')
"

# Start with explicit Rich mode
FORCE_RICH=1 lobster chat

# Or disable if causing issues
DISABLE_RICH=1 lobster chat

⚠️  Rate Limit Exceeded
Error code: 429 - {'type': 'error', 'error': {'type': 'rate_limit_error', 'message': 'This request would exceed your organization's maximum usage increase rate...'}}

# Wait 60 seconds and retry
# Rate limits typically reset within 1-2 minutes

# Check current rate limit status
🦞 You: "What are my current API rate limits?"

# 1. Request rate limit increase from Anthropic
# Visit: https://docs.anthropic.com/en/api/rate-limits
# Fill out their rate increase request form

# 2. Reduce concurrent requests
# Run analysis tasks sequentially instead of parallel

# 3. Use retry logic with exponential backoff
# Lobster AI will automatically retry with delays

# Switch to AWS Bedrock (enterprise-grade limits)
# 1. Set up AWS Bedrock credentials
cat > .env << EOF
AWS_BEDROCK_ACCESS_KEY=your-aws-access-key
AWS_BEDROCK_SECRET_ACCESS_KEY=your-aws-secret-key
EOF

# 2. Restart Lobster
lobster chat

# 3. Verify Bedrock connection
🦞 You: "/session"  # Check which provider is active

# For urgent rate limit increases or assistance:
# Email: info@omics-os.com
# Include:
# - Your organization ID (from error message)
# - Use case description
# - Expected usage volume

🔑 Authentication Failed
Error code: 401 - {'type': 'error', 'error': {'type': 'invalid_api_key'}}

# Check environment variables
echo $ANTHROPIC_API_KEY    # Should show: sk-ant-api03-...
echo $AWS_BEDROCK_ACCESS_KEY  # For AWS users

# Check .env file
cat .env

# Ensure proper format (no quotes, spaces, or line breaks)
ANTHROPIC_API_KEY=sk-ant-api03-your-actual-key-here

# 1. Key in .env but not loaded
source .env && lobster chat

# 2. Key has extra whitespace
# Edit .env and remove any spaces:
# ✓ ANTHROPIC_API_KEY=sk-ant-...
# ✗ ANTHROPIC_API_KEY = sk-ant-...
# ✗ ANTHROPIC_API_KEY="sk-ant-..."

# 3. Generate new key
# Visit https://console.anthropic.com/settings/keys
# Create new key and update .env

# Test authentication
python -c "
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ.get('ANTHROPIC_API_KEY'))
print('✓ Authentication successful')
"

# If using AWS Bedrock, verify IAM permissions include:
# - bedrock:InvokeModel
# - bedrock:InvokeModelWithResponseStream

# Test AWS credentials
aws bedrock list-foundation-models --region us-east-1

🌐 Network Error
Connection timeout / Connection refused / DNS resolution failed

# Test internet connection
ping -c 3 anthropic.com
ping -c 3 api.anthropic.com

# Test HTTPS access
curl -I https://api.anthropic.com/v1/messages

# Check DNS resolution
nslookup api.anthropic.com

# Ensure firewall allows HTTPS (port 443)
# For corporate networks, contact IT to whitelist:
# - api.anthropic.com
# - bedrock-runtime.*.amazonaws.com (for AWS)

# Test with firewall temporarily disabled
sudo ufw disable  # Linux
# Try connection, then re-enable
sudo ufw enable

# If behind a proxy, set environment variables
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# Test with proxy
lobster chat

# Check Anthropic service status
# Visit: https://status.anthropic.com

# For AWS Bedrock
# Visit: https://status.aws.amazon.com

💳 Usage Quota Exceeded
Error code: 402 - insufficient_quota

# 1. Visit billing dashboard
# Anthropic: https://console.anthropic.com/settings/billing
# Check current usage and limits

# 2. Review usage metrics
# - Current month usage
# - Remaining quota
# - Next reset date

# 1. Upgrade plan or add credits
# 2. Set up automatic billing
# 3. Contact billing support for enterprise quotas

# For AWS Bedrock users:
# Contact AWS support for quota increases
# Visit: https://console.aws.amazon.com/support

# Switch to AWS Bedrock for higher quotas
# See installation guide for AWS setup
# wiki/02-installation.md#aws-bedrock-access

⚠️  FTP download failed after 3 retries
Corrupted gzip file detected
File size mismatches (140-285% larger than expected)
Gzip errors: "not in gzip format", "invalid header", "CRC check failed"

1. HTTPS pre-download of SOFT file (99% of cases)
   ↓ (if HTTPS fails)
2. GEOparse FTP fallback (rare)
   ↓ (if FTP fails)
3. Next pipeline step (multiple strategies)

# Clear cache and force fresh download
rm -rf ~/.lobster_workspace/cache/geo/GSE12345*
🦞 You: "Download GSE12345 with fresh cache"

# Check internet connectivity (HTTPS, not FTP)
ping ftp.ncbi.nlm.nih.gov

# Verify GEO accession exists
🦞 You: "Search for GSE12345 in GEO database"

# macOS - Install Python certificates
cd "/Applications/Python 3.12/"
./Install Certificates.command

# Linux (Ubuntu/Debian) - Update CA certificates
sudo apt-get install ca-certificates
sudo update-ca-certificates

# Linux (Fedora/RHEL)
sudo dnf install ca-certificates
sudo update-ca-trust

⚠️  Duplicate cell barcodes detected: 48%
Dataset GSE248556 rejected due to data quality issues
Validation failed: non-unique cell barcodes

# System automatically detects VDJ datasets
🦞 You: "Download GSE248556"
# Output: "Detected VDJ/TCR sequencing data, accepting duplicate barcodes (48%)"

🦞 You: "Load GSE248556 treating samples as VDJ data"
🦞 You: "Override duplicate barcode validation for immunology dataset"

TypeError: Can't implicitly convert non-string objects to strings
TypeError: Cannot serialize mixed types to H5AD
ValueError: Boolean values not supported in AnnData metadata
KeyError: Metadata column contains None values

# Problematic metadata structure:
{
    'contact_zip/postal_code': 12345,  # ❌ int cannot be serialized
    'sample_count': 13,  # ❌ int cannot be serialized
    'is_processed': True,  # ❌ bool cannot be serialized
    'platforms': ['GPL20795', 'GPL24676'],  # ❌ list cannot be serialized
    'submission_date': None,  # ❌ None cannot be serialized
}

# Check metadata before export
🦞 You: "Show metadata summary for current dataset"

# Force H5AD export with sanitization (automatic in v0.2+)
🦞 You: "Export to H5AD"

⚠️  Matrix dimensions may be inverted: 187,697 features × 4 observations
Expected: samples × genes for bulk RNA-seq
Applying automatic transpose...

# If auto-transpose is incorrect (very rare)
🦞 You: "Load GSE12345 without auto-transpose"
🦞 You: "Keep original matrix orientation for GSE12345"

❌ Invalid accession format: GDS200157007
Expected format: GSE/GSM/GPL/GDS + digits
Accession has 9 digits, expected 4-7

# Verify accession format
🦞 You: "Search for GSE157007 in GEO database and verify accession format"

# System now returns correct format automatically
# GSE prefix: Series (multiple samples)
# GSM prefix: Sample (single sample)
# GPL prefix: Platform (array/sequencing tech)
# GDS prefix: Curated dataset (deprecated but still supported)

🦞 You: "Search for GSE12345 in GEO database and verify it exists"
🦞 You: "Download GSE12345 with verbose output to see detailed progress"

# Check internet connectivity
ping ncbi.nlm.nih.gov

# Use alternative download method
🦞 You: "Download GSE12345 using alternative mirror or cached version"

# Manual download and load
🦞 You: "Load local file that I downloaded manually from GEO"

# Clear GEO cache
rm -rf ~/.lobster_workspace/geo_cache/

# Retry download
🦞 You: "Download GSE12345 with fresh cache"

🦞 You: "Load CSV file with genes as rows and samples as columns"
🦞 You: "Load TSV file with tab separators and first row as header"
🦞 You: "Load Excel file from sheet named 'RNAseq_data'"

# Check file encoding
file -i your_data.csv

# Convert if needed
iconv -f iso-8859-1 -t utf-8 your_data.csv > your_data_utf8.csv

🦞 You: "This is a count matrix with gene symbols in first column, sample IDs in header row"
🦞 You: "The file has metadata in the first 3 rows, data starts from row 4"
🦞 You: "File uses semicolon separators instead of commas"

🦞 You: "Load large file in chunks of 10000 rows to save memory"
🦞 You: "Subsample 50% of the data for initial exploration"
🦞 You: "Use sparse matrix format to reduce memory usage"

# Convert to more efficient format
🦞 You: "Convert CSV to H5AD format for faster loading"
🦞 You: "Compress data using sparse matrix representation"

# Monitor memory usage
🦞 You: "/dashboard"  # Check system resources

# Use cloud processing for large files
export LOBSTER_CLOUD_KEY="your-api-key"
🦞 You: "Process this large dataset using cloud resources"

# Install Docling with all dependencies
pip install docling

# Verify installation
python -c "from docling.document_converter import DocumentConverter; print('✓ Docling installed')"

# For enhanced table extraction
pip install "docling[table]"

# For OCR support (PDFs with scanned images)
pip install "docling[ocr]"

# Full installation with all features
pip install "docling[all]"

🦞 You: "Test Docling installation by extracting methods from a sample paper"
🦞 You: "Extract methods from PMID:38448586 using Docling"

MemoryError: Unable to allocate memory for document parsing
RuntimeError: PDF parsing failed after 2 retries

# Clear memory before parsing
🦞 You: "Clear workspace cache to free memory"
python -c "import gc; gc.collect()"

# Parse one document at a time
🦞 You: "Extract methods from PMID:12345678"  # Sequential processing
# Wait for completion before starting next extraction

# Docling automatically retries with garbage collection
# The retry logic handles MemoryError automatically
# Just wait for the automatic retry to complete

# For very large PDFs, use PyPDF2 fallback explicitly
🦞 You: "Extract methods using PyPDF2 fallback for memory efficiency"

# Check available memory
free -h  # Linux
vm_stat  # macOS

# Monitor during extraction
🦞 You: "/dashboard"  # Check memory usage in real-time

# Process papers sequentially (not in parallel)
🦞 You: "Extract methods from these papers one at a time: PMID:123, PMID:456, PMID:789"

# Clear cache between large documents
rm -rf ~/.lobster_workspace/literature_cache/parsed_docs/

⚠️  Could not resolve DOI to accessible URL
Failed to extract content from identifier: 10.1038/...
PaywalledError: Paper 10.18632/aging.204666 is paywalled

# Test if identifier is detected correctly
🦞 You: "Check if DOI:10.1038/s41586-025-09686-5 is accessible"

# System will show resolution attempt and results:
# "✓ Detected identifier (DOI): 10.1038/..., resolving to URL..."
# "✓ Resolved to: https://www.nature.com/articles/..."
# OR
# "⚠️ Paper is not accessible: paywalled"

# If DOI doesn't resolve, try the PMID
🦞 You: "Extract methods from PMID:38448586"

# Or search for preprint version
🦞 You: "Find bioRxiv preprint for cellular senescence human fibroblasts"

# If you have institutional access, provide the article page URL directly
🦞 You: "Extract methods from https://www.nature.com/articles/s41586-025-09686-5"

# For PMC papers, try the main article page (not /pdf/ directory)
🦞 You: "Extract methods from https://www.ncbi.nlm.nih.gov/pmc/articles/PMC12496192/"

# Successful resolution shows:
INFO Detected identifier (DOI): 10.1101/..., resolving to URL...
INFO Resolved via preprint server: https://www.biorxiv.org/content/...
INFO Content extraction successful (pdf auto-detected) in 2.3s

# Failed resolution shows:
WARNING Paper 10.18632/aging.204666 is not accessible: paywalled
INFO Alternative suggestions: [institutional access, preprints, author contact]

⚠️  Methods section not found in document
Extracted 0 paragraphs from Methods section

🦞 You: "Show me the document structure and available sections"
🦞 You: "List all section headings found in the paper"

# Docling searches for these keywords by default:
# "method", "material", "experimental", "procedure", "analysis"
#
# If paper uses non-standard terms, Docling may miss the section

# Check if paper is accessible
🦞 You: "Check if PMID:12345678 is accessible"

# Try extraction with PyPDF2 fallback
# (captures more text but less structured)

# View full PDF text to check section names
🦞 You: "Extract full text from the paper to identify section structure"

# Check if paper has Methods at all
# Some papers (reviews, perspectives) may not have Methods sections

# If you see "page-dimensions" RuntimeError:
# This indicates an incompatible PDF format
# System will automatically fall back to PyPDF2

# Verify fallback behavior
🦞 You: "Extract methods from PMID:12345678"
# Check provenance metadata: {"parser": "pypdf2", "fallback": true}

RuntimeError: PDF contains page-dimensions errors
Falling back to PyPDF2 after detecting incompatible PDF format

# Docling automatically detects this error and falls back to PyPDF2
# Extraction continues with reduced functionality:
# - Methods section still extracted (lower hit rate)
# - Tables won't be extracted
# - Formulas won't be detected
# - Provenance will show: {"parser": "pypdf2", "fallback": true}

🦞 You: "Extract methods from PMID:12345678"
# Check response for "Extraction completed using PyPDF2 fallback"

# Verify provenance metadata
🦞 You: "Show extraction provenance for the last paper"
# Should show: {"parser": "pypdf2", "fallback": true, "fallback_reason": "page-dimensions"}

# Attempt to repair PDF with external tools
# Only if PyPDF2 fallback also fails

# Option 1: Ghostscript repair
gs -o repaired.pdf -sDEVICE=pdfwrite -dPDFSETTINGS=/prepress original.pdf

# Option 2: qpdf repair
qpdf --linearize original.pdf repaired.pdf

# Then try extraction again
🦞 You: "Extract methods from repaired.pdf"

# Remove all cached documents
rm -rf ~/.lobster_workspace/literature_cache/parsed_docs/

# Clear specific paper cache
# Cache files named by MD5 hash of source URL
# Example: parsed_docs/abc123def456.json

# Check cache directory exists and is writable
ls -la ~/.lobster_workspace/literature_cache/parsed_docs/

# Check cache file sizes
du -sh ~/.lobster_workspace/literature_cache/
# Typical: 500KB-2MB per paper

# Cache hit: <100ms
# Cache miss (first parse): 2-5 seconds

# You'll see timing in responses:
# "Extraction completed in 0.08s (cached)" - Cache hit
# "Extraction completed in 3.2s" - Fresh parse

# Cache is persistent across sessions (good for reproducibility)
# Automatic cache invalidation not implemented
# Manual cleanup recommended if:
# - Papers are updated/corrected by publishers
# - Testing different extraction parameters
# - Cache directory exceeds 1GB

# Selective cache cleanup
cd ~/.lobster_workspace/literature_cache/parsed_docs/
# Delete specific paper cache by finding its MD5 hash

# Process 2-5 papers at a time (not more)
🦞 You: "Extract methods from PMID:123, PMID:456, PMID:789"

# System processes sequentially to avoid memory issues
# Wait for batch completion before starting next batch

# Docling's built-in retry logic:
# 1. First attempt: Parse with Docling
# 2. MemoryError → gc.collect() → Retry
# 3. Second MemoryError → Fall back to PyPDF2
# 4. RuntimeError (page-dimensions) → Immediate PyPDF2 fallback

# You don't need to manage retries manually

🦞 You: "Show QC metric distributions before applying any filters"
🦞 You: "What are the recommended QC thresholds for this data type?"

🦞 You: "Use more lenient QC thresholds: >500 genes per cell and <30% mitochondrial"
🦞 You: "Filter based on median absolute deviation instead of fixed thresholds"
🦞 You: "Show me the effect of different threshold combinations"

🦞 You: "Is this data extremely low quality or are the thresholds inappropriate?"
🦞 You: "Generate comprehensive QC report with recommendations"
🦞 You: "Compare QC metrics to typical ranges for this experiment type"

🦞 You: "Test clustering resolutions from 0.1 to 2.0 and show silhouette scores"
🦞 You: "Try different clustering algorithms: Leiden, Louvain, hierarchical"
🦞 You: "Adjust number of neighbors from 5 to 50 and compare results"

🦞 You: "Verify that data normalization was applied correctly"
🦞 You: "Check if highly variable genes were identified properly"
🦞 You: "Ensure PCA was computed with appropriate number of components"

🦞 You: "Generate PCA plot to check for obvious batch effects"
🦞 You: "Show UMAP plot to assess overall data structure"
🦞 You: "Calculate and plot variance explained by each PC"

🦞 You: "How many samples per group do I have? Is this sufficient for DE analysis?"
🦞 You: "Calculate power analysis for detecting 2-fold changes"
🦞 You: "Show distribution of fold changes even if not significant"

🦞 You: "Use less stringent FDR threshold (0.1 instead of 0.05)"
🦞 You: "Try different statistical methods: DESeq2, edgeR, limma"
🦞 You: "Test for fold change thresholds: |log2FC| > 0.5"

🦞 You: "Check if experimental conditions are properly balanced"
🦞 You: "Look for confounding factors in sample metadata"
🦞 You: "Generate PCA plot colored by treatment to see separation"

🦞 You: "/progress"  # Check current operations
🦞 You: "/dashboard"  # Monitor system resources

🦞 You: "Use faster approximate methods for initial exploration"
🦞 You: "Reduce number of genes/cells for testing parameters"
🦞 You: "Enable parallel processing using multiple CPU cores"

# Switch to cloud for intensive analyses
export LOBSTER_CLOUD_KEY="your-api-key"
🦞 You: "Move this analysis to cloud infrastructure for faster processing"

🦞 You: "Convert to sparse matrix format to save memory"
🦞 You: "Process data in smaller chunks"
🦞 You: "Remove unnecessary variables from workspace"

🦞 You: "Use int32 instead of int64 for count data"
🦞 You: "Apply gene filtering to reduce matrix size"
🦞 You: "Subsample cells for parameter testing"

🦞 You: "/dashboard"  # Check memory consumption
🦞 You: "Show memory usage of current datasets"

🦞 You: "/plots"  # List available plots
🦞 You: "Generate simple scatter plot to test visualization system"

🦞 You: "Do I have the required data for this plot type?"
🦞 You: "Show me the data structure needed for UMAP visualization"

🦞 You: "Create UMAP plot with different parameters"
🦞 You: "Generate static plot instead of interactive version"
🦞 You: "Export plot data for external visualization"

🦞 You: "Create high-resolution plot (300 DPI) suitable for publication"
🦞 You: "Use distinct colors for better cluster separation"
🦞 You: "Adjust point sizes and transparency for better visibility"

🦞 You: "Generate plot with custom color palette"
🦞 You: "Create plot with larger fonts for better readability"
🦞 You: "Export plot with editable text for post-processing"

# Check API key is set
echo $LOBSTER_CLOUD_KEY

# Test cloud connectivity
🦞 You: "/session"  # Should show provider and session info

# Temporarily disable cloud
unset LOBSTER_CLOUD_KEY
🦞 You: "Continue analysis in local mode"

# Re-export API key
export LOBSTER_CLOUD_KEY="your-api-key"
🦞 You: "Test cloud connection and retry analysis"

🦞 You: "Use cloud-optimized analysis parameters"
🦞 You: "Split large analyses into smaller chunks"

# Test network speed
speedtest-cli

# Use local processing for small analyses
🦞 You: "Process this small dataset locally to save time"

🦞 You: "/status"  # Check available agents
🦞 You: "List all available agents and their capabilities"

🦞 You: "Use the single-cell expert to analyze this scRNA-seq data"
🦞 You: "Hand this proteomics task to the MS proteomics expert"

# Exit and restart Lobster
🦞 You: "/exit"
lobster chat  # Fresh session

🦞 You: "What data is required for this analysis?"
🦞 You: "Verify that my data meets the requirements"

🦞 You: "Try alternative method for this analysis"
🦞 You: "Use simpler version of this analysis"

🦞 You: "Show detailed error message and suggest solutions"
🦞 You: "Generate debug information for this failed analysis"

🦞 You: "/dashboard"  # Check system status
htop  # Monitor processes externally

🦞 You: "Kill any running background processes"
🦞 You: "Reduce analysis complexity to save resources"
🦞 You: "Clear workspace cache to free memory"

🦞 You: "Use single-threaded processing to reduce CPU load"
🦞 You: "Process data in smaller batches"

# Verify write permissions
ls -la ./
🦞 You: "Export to a different directory with write permissions"

🦞 You: "Export results as CSV files"
🦞 You: "Save plots in PNG format instead of SVG"
🦞 You: "Export data in H5AD format for preservation"

🦞 You: "/export results"  # Use CLI export command
🦞 You: "Show me the data so I can copy it manually"

🦞 You: "Show me all completed analyses in this session"
🦞 You: "/data"  # Check loaded datasets
🦞 You: "/files"  # List all available files

🦞 You: "Re-run the differential expression analysis"
🦞 You: "Recreate the clustering analysis from preprocessed data"

🦞 You: "Show analysis history and provenance tracking"
🦞 You: "Export session log with all commands and results"

# Start with debug mode
LOBSTER_DEBUG=1 lobster chat

# Check log files
tail -f ~/.lobster/logs/lobster.log

🦞 You: "Enable detailed error reporting for troubleshooting"
🦞 You: "Show me the complete error traceback"
🦞 You: "Generate diagnostic report for this issue"

# Access data manager directly
from lobster.core.data_manager_v2 import DataManagerV2
from pathlib import Path

dm = DataManagerV2(workspace_path=Path(".lobster_workspace"))
print(dm.list_modalities())

# Inspect specific dataset
adata = dm.get_modality("your_dataset_name")
print(adata.obs.head())

# Test individual services
from lobster.tools.preprocessing_service import PreprocessingService

service = PreprocessingService()
# Test service methods directly

# Backup current workspace
cp -r .lobster_workspace .lobster_workspace_backup

# Clean and reinitialize
🦞 You: "Initialize fresh workspace and reload data"

# Save current state
🦞 You: "/export session-state"

# Restart and restore
lobster chat
🦞 You: "/import session-state"

ERROR: ContentAccessService not available or not initialized
ERROR: No providers registered for capability

# Verify service is available
lobster chat
> "Query available capabilities"

# Should show:
# - AbstractProvider (fast abstracts)
# - PubMedProvider (literature search)
# - GEOProvider (dataset discovery)
# - PMCProvider (full-text, priority)
# - WebpageProvider (fallback, PDF support)

# Check which providers are active
> "What providers are available for literature access?"

# Expected output shows all 5 providers with priorities

# Install Docling for PDF support
pip install lobster[docling]

# Verify installation
python -c "import docling; print('Docling OK')"

# Clean workspace and restart
rm -rf ~/.lobster_workspace/
lobster chat --workspace ~/.lobster_new

ERROR: Failed to parse PDF content
WARNING: Docling service failed to extract content
MemoryError during PDF parsing

# Full Docling installation
pip install lobster[docling]

# Verify dependencies
python -c "import docling.document_converter; print('Docling installed')"

# For PDFs >50MB, increase memory limit
export LOBSTER_MAX_FILE_SIZE_MB=500

# Or use abstract-only for initial review
> "Get abstract for PMID:12345"  # Fast, always works

# If Docling fails, system automatically falls back to PyPDF2
# No action needed - fallback is automatic

# Manually request abstract instead of full-text
> "Extract abstract and keywords from PMID:12345"

# Test PDF integrity
pdfinfo your_file.pdf

# For scanned PDFs, use OCR first
# (Docling doesn't support image-only PDFs)

ERROR: HTTP 429 Too Many Requests
WARNING: Rate limit exceeded for webpage extraction
ERROR: Publisher blocking automated access

# ContentAccessService tries PMC XML API first (fast, no rate limits)
> "Read full publication PMID:35042229"

# PMC covers 30-40% of biomedical literature
# 10x faster than webpage scraping

# Service implements exponential backoff automatically
# Just wait and retry after 60 seconds

# Check capabilities to see which providers are available
> "Query capabilities"

# Direct DOI URLs often work better than publisher pages
> "Read content from https://doi.org/10.1038/s41586-021-12345-6"

# Search for open access versions
> "Search bioRxiv for BRCA1 breast cancer"

# Filter by open access
> "Search literature cancer therapy filters:open_access=true"

ERROR: Content is behind paywall
INFO: PMC full-text not available for this publication
WARNING: Paper is not accessible: paywalled

# System automatically tries:
# 1. PMC XML API (30-40% coverage, fast)
# 2. Webpage/PDF extraction (60-70% coverage, slower)
# 3. Error with suggestions if paywalled

> "Read full publication PMID:12345"
# Automatic cascade - no manual intervention needed

# For paywalled papers, get what you can
> "Get abstract for PMID:12345"
> "Extract methods from abstract"  # Limited but useful

> "Find bioRxiv preprint for [paper title]"
> "Search medRxiv for COVID-19 clinical trial"

> "Is PMID:12345 available in open access?"
> "Find open access version of DOI:10.1038/xxx"

ERROR: Identifier 'publication_PMID12345' not found in workspace
FileNotFoundError: ~/.lobster_workspace/literature/pmid_12345.json

# Check what's actually cached
> "What content do I have cached?"
> "Show me cached publications"
> "List all cached datasets"

# Use /workspace command
> /workspace

# Correct format: lowercase with underscores
# ✅ Correct: publication_PMID35042229
# ❌ Wrong: PMID:35042229 (has colon)
# ❌ Wrong: publication_pmid_35042229 (duplicate prefix)

# Check identifier in cache directory
ls ~/.lobster_workspace/literature/

# Must cache before accessing
> "Read full publication PMID:35042229"
# This automatically caches to workspace

# Or explicitly cache
> "Cache PMID:35042229 in literature workspace"

# Check workspace exists
ls -la ~/.lobster_workspace/

# Should have subdirectories:
# - literature/
# - data/
# - metadata/

# Check in Lobster
> /workspace

ERROR: Permission denied: ~/.lobster_workspace/literature/
ERROR: Cannot create directory
OSError: [Errno 30] Read-only file system

# Create all required directories
mkdir -p ~/.lobster_workspace/{literature,data,metadata}
chmod 755 ~/.lobster_workspace/

# Verify creation
ls -la ~/.lobster_workspace/

# Fix ownership
chown -R $USER:$USER ~/.lobster_workspace/

# Fix permissions
chmod -R u+rw ~/.lobster_workspace/

# Check available space
df -h ~

# If disk full, clean old caches
du -sh ~/.lobster_workspace/
find ~/.lobster_workspace/ -mtime +30 -delete  # Remove files >30 days old

# Specify different workspace path
export LOBSTER_WORKSPACE=/path/to/workspace
lobster chat

# Or at runtime
lobster chat --workspace /mnt/data/lobster_workspace

PermissionError: [Errno 13] Permission denied: '~/.lobster_workspace/literature/pmid_12345.json'

# Take ownership of all workspace files
chown -R $USER:$USER ~/.lobster_workspace/

# Make files readable/writable
chmod -R u+rw ~/.lobster_workspace/

# For directories, add execute permission
chmod -R u+rwx ~/.lobster_workspace/*/

# Check if SELinux is enforcing
getenforce

# If 'Enforcing', temporarily disable for testing
sudo setenforce 0

# Or configure SELinux policy properly
# (production systems should not disable SELinux)

# Nuclear option: delete and recreate
rm -rf ~/.lobster_workspace/
lobster chat  # Will recreate with correct permissions

# Check cache statistics
> /workspace
# Shows: cached publications, datasets, metadata

# List cached content by type
> "Show me all cached publications"
> "List cached datasets"

# Check cache directory directly
ls -lh ~/.lobster_workspace/literature/
ls -lh ~/.lobster_workspace/data/

# Bypass cache and re-fetch
> "Read full publication PMID:12345 with force refresh"

# Delete specific cache file
rm ~/.lobster_workspace/literature/pmid_35042229.json

# Delete specific cached item
rm ~/.lobster_workspace/literature/pmid_35042229.json

# Clear all cached publications
rm -rf ~/.lobster_workspace/literature/*.json

# Clear all cached datasets
rm -rf ~/.lobster_workspace/data/*.json

# Nuclear option: clear entire workspace
rm -rf ~/.lobster_workspace/
lobster chat  # Starts fresh

# Cached content has timestamps
# Service checks age before using
# Default TTL:
# - Publications: 7 days
# - Datasets: 24 hours (metadata changes frequently)
# - Metadata: 24 hours

# No manual invalidation needed for most cases

ERROR: No space left on device
WARNING: Workspace size exceeding 1GB
OSError: [Errno 28] No space left on device

# Check total workspace size
du -sh ~/.lobster_workspace/

# Break down by subdirectory
du -h ~/.lobster_workspace/ | sort -h

# Find largest cached items
find ~/.lobster_workspace/ -type f -size +10M -exec ls -lh {} \;

# Check available disk space
df -h ~

# Remove files older than 30 days
find ~/.lobster_workspace/ -type f -mtime +30 -delete

# Remove files older than 7 days
find ~/.lobster_workspace/ -type f -mtime +7 -delete

# Verify cleanup
du -sh ~/.lobster_workspace/

# Backup to compressed archive
tar -czf lobster_workspace_backup_$(date +%Y%m%d).tar.gz ~/.lobster_workspace/

# Delete old workspace
rm -rf ~/.lobster_workspace/

# Restore if needed
tar -xzf lobster_workspace_backup_YYYYMMDD.tar.gz -C ~/

# Set maximum workspace size
export LOBSTER_MAX_WORKSPACE_SIZE_MB=500
lobster chat

# Service will warn when limit approached

# Move workspace to external/network drive
mv ~/.lobster_workspace /mnt/large_disk/lobster_workspace

# Create symbolic link
ln -s /mnt/large_disk/lobster_workspace ~/.lobster_workspace

# Verify
ls -la ~/.lobster_workspace

ERROR: PyMOL not found in PATH
WARNING: PyMOL visualization will not execute
INFO: Command script generated at: 1AKE_commands.pml

# Check PyMOL installation
which pymol

# Test PyMOL (headless mode)
pymol -c -Q

# Check version
pymol -c -r "print(cmd.get_version())"

# Use Makefile (recommended)
cd lobster
make install-pymol

# Verify
pymol -c -Q

# Install via Homebrew
brew install brewsci/bio/pymol

# Verify installation
which pymol
pymol -c -Q

# Install from repositories
sudo apt-get update
sudo apt-get install pymol

# Verify
which pymol

# Install via DNF
sudo dnf install pymol

# Verify
which pymol

# PyMOL is pre-installed in Docker image
docker run -it omicsos/lobster:latest pymol -c -Q

# No installation needed in Docker

# Download from https://pymol.org/
# Install using GUI installer
# Add to PATH via System Environment Variables

# Agent still generates command scripts
> "Visualize protein structure 1AKE"

# Manual execution later when PyMOL installed
pymol 1AKE_commands.pml  # Interactive mode
pymol -c 1AKE_commands.pml  # Batch mode (headless)

ERROR: Failed to parse PDB file: 1AKE.pdb
ERROR: Invalid PDB ID format
ValueError: PDB ID must be 4 characters

# ✅ Correct formats:
# - 1AKE (4 chars, alphanumeric)
# - 4HHB, 3A5D, 7BV2

# ❌ Wrong formats:
# - AKE (too short)
# - 1AKEE (too long)
# - 1-AKE (invalid character: hyphen)
# - 1ake (works but use uppercase for consistency)

# Use correct format
> "Fetch protein structure 1AKE"

# Use cached version
> "Fetch protein structure 1AKE"

# Force re-download
> "Fetch protein structure 1AKE with force refresh"

# Verify file integrity
ls -lh protein_structures/1AKE.*
# Should be >10KB for valid structure

# mmCIF format (default, recommended)
> "Fetch protein structure 1AKE format=cif"

# Legacy PDB format
> "Fetch protein structure 1AKE format=pdb"

# Check on RCSB website
# https://www.rcsb.org/structure/1AKE

# Search for alternative structures
> "Find protein structures for gene BRCA1"

ERROR: PyMOL execution timed out
ERROR: Failed to generate visualization
WARNING: PyMOL process exited with error code 1

# Batch mode is faster, no GUI required
> "Visualize 1AKE with PyMOL mode=batch"

# Generates PNG image without opening GUI

# Cartoon is fastest (default)
> "Visualize 1AKE style=cartoon"

# Surface/spheres are slower
> "Visualize 1AKE style=surface"  # Slower, more memory

# Fetch structure first to see metadata
> "Fetch protein structure 1AKE"

# Look for: "Total atoms: X" in output
# If >100K atoms, expect longer rendering time

# For very large structures
export LOBSTER_PYMOL_TIMEOUT_SECONDS=300

# Restart Lobster
lobster chat

# Generate PNG without GUI
pymol -c 1AKE_commands.pml

# Faster than interactive mode

# Linux
free -h

# macOS
vm_stat

# Ensure >2GB free for large structures

INFO: Launching PyMOL GUI...
WARNING: PyMOL GUI did not launch
ERROR: DISPLAY environment variable not set

# Should be set for GUI apps
echo $DISPLAY

# Expected values:
# - :0 (local display)
# - localhost:10.0 (X11 forwarding)

# SSH with X11 forwarding
ssh -X user@host

# Or on macOS (requires XQuartz)
ssh -Y user@host

# Simple X11 test
xeyes  # Should show GUI window

# If xeyes fails, X11 not configured

# Batch mode doesn't require display
> "Visualize 1AKE mode=batch style=cartoon"

# Generates PNG without GUI

# Save command script now
> "Visualize 1AKE execute=false"

# Execute later when you have GUI access
pymol 1AKE_commands.pml

ERROR: Unable to locate credentials
ERROR: S3 backend connection failed
botocore.exceptions.NoCredentialsError

# Interactive configuration
aws configure

# Enter:
# AWS Access Key ID: AKIAIOSFODNN7EXAMPLE
# AWS Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# Default region: us-east-1
# Default output format: json

# Export credentials
export AWS_ACCESS_KEY_ID=your_key_id
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_DEFAULT_REGION=us-east-1

# Verify
echo $AWS_ACCESS_KEY_ID

# Create credentials file
mkdir -p ~/.aws
cat > ~/.aws/credentials << EOF
[default]
aws_access_key_id = your_key_id
aws_secret_access_key = your_secret_key
EOF

# Set permissions
chmod 600 ~/.aws/credentials

# Test S3 access
aws s3 ls

# Should list your buckets
# If error, credentials are wrong

lobster chat
> "Use S3 backend for storage"
> /session  # Should show session info with loaded data

ERROR: Access Denied (403)
ERROR: Cannot write to S3 bucket: your-bucket-name
botocore.exceptions.ClientError: An error occurred (AccessDenied)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

# Test bucket listing
aws s3 ls s3://your-bucket-name/

# Test write permission
echo "test" | aws s3 cp - s3://your-bucket-name/test.txt

# Test read permission
aws s3 cp s3://your-bucket-name/test.txt -

# Test delete permission
aws s3 rm s3://your-bucket-name/test.txt

# Get user policies
aws iam list-user-policies --user-name your-username

# Get policy document
aws iam get-user-policy --user-name your-username --policy-name your-policy

# If permissions insufficient, contact AWS admin
# Or create new IAM user with correct permissions

# Alternative: Use local storage
> "Use local filesystem backend instead of S3"

ERROR: Connection timeout to S3
ERROR: Unable to reach S3 endpoint
requests.exceptions.ConnectionError: Max retries exceeded
botocore.exceptions.EndpointConnectionError

# Ping S3 endpoint
ping s3.amazonaws.com

# Test HTTPS connection
curl -I https://s3.amazonaws.com

# Should return HTTP 403 (forbidden but reachable)

# Change default region
export AWS_DEFAULT_REGION=us-west-2
lobster chat

# Or specify in config
aws configure set default.region us-west-2

# Test DNS lookup
nslookup s3.amazonaws.com

# Should resolve to AWS IP addresses

# If running in AWS EC2/ECS
export AWS_S3_ENDPOINT=https://vpce-xxxxx.s3.us-east-1.vpce.amazonaws.com

# VPC endpoints bypass internet gateway

# For slow connections
export LOBSTER_S3_TIMEOUT_SECONDS=60
lobster chat

# Ensure outbound HTTPS (443) allowed to:
# - s3.amazonaws.com
# - *.s3.amazonaws.com
# - s3.us-east-1.amazonaws.com (region-specific)

# If S3 unavailable, switch to local
> "Use local filesystem backend"
> /session  # Verify session workspace

🦞 You: "Run system diagnostics and generate troubleshooting report"