Troubleshooting

Solutions to common issues when using Omics-OS Cloud.

Connection Issues

"Failed to connect to server"

Symptoms:

• Chat doesn't load
• Spinning loader indefinitely
• Network error in browser console

Solutions:

1. Check your internet connection

   Try loading another website to verify connectivity

2. Refresh the page

   • Press Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows) for hard refresh

3. Check service status

   • Visit status.omics-os.com for outage information

4. Try incognito/private mode

   • Browser extensions can sometimes interfere

---

Session expired

Symptoms:

• "Session not found" error
• Redirected to home page
• Lost conversation history

Cause: Anonymous sessions expire after 24 hours.

Solutions:

1. Sign up for an account to preserve your work
2. Start a new session (your uploaded files may need to be re-uploaded)

---

Chat Issues

Agent not responding

Symptoms:

• Message sent but no response
• Stuck on "Thinking..."
• Timeout after long wait

Solutions:

1. Wait a moment — Complex analyses can take 30+ seconds
2. Check for errors — Scroll up to see if an error was returned
3. Simplify your request — Break complex workflows into steps
4. Refresh and retry — Sometimes reconnecting helps

---

"I don't understand" responses

Symptoms:

• Agent asks for clarification repeatedly
• Wrong agent handles your request
• Irrelevant responses

Solutions:

1. Be more specific:

   Instead of: "Analyze my data"
   Try: "Load my_data.h5ad and run quality control on the single-cell data"

2. Provide context:

   "I have bulk RNA-seq count data from mouse liver.
    There are 4 treatment and 4 control samples.
    Can you run differential expression analysis?"

3. Name the agent directly:

   "Research Agent: Search PubMed for CRISPR papers"

---

File Upload Issues

"Upload failed"

Symptoms:

• File upload never completes
• Error message after upload attempt
• Progress bar stuck

Solutions:

1. Check file size — Max 500MB for most formats
2. Check file format — See supported formats
3. Try compression — Upload as .gz if large
4. Check file integrity — Try opening the file locally first

---

"Unsupported format"

Symptoms:

• "Cannot read file" error
• Format not recognized

Solutions:

1. Use recommended formats:

   • Single-cell: .h5ad (AnnData)
   • Bulk RNA-seq: .csv count matrix
   • Proteomics: Spectronaut/DIA-NN .tsv

2. Convert your data:

   # Convert Seurat to h5ad
   library(Seurat)
   SaveH5Seurat(seurat_object, filename = "data.h5seurat")
   Convert("data.h5seurat", dest = "h5ad")

---

"File too large"

Symptoms:

• Upload rejected
• "Exceeds size limit" error

Solutions:

1. Compress the file:

   gzip large_file.csv
   # Upload large_file.csv.gz

2. Subset your data:

   # Subset to fewer cells
   adata = adata[adata.obs.sample(n=50000).index]
   adata.write("subset.h5ad")

3. Use database accession instead:

   "Download GEO dataset GSE198765"

4. Upgrade your tier for larger limits

---

Analysis Issues

"Analysis failed"

Symptoms:

• Error message during processing
• Incomplete results
• Agent reports failure

Solutions:

1. Check your data:

   • Are there missing values?
   • Are gene IDs in a recognized format?
   • Do sample IDs match between data and metadata?

2. Read the error message:

   Error: "No cells remaining after QC filtering"
   → Your QC thresholds may be too strict
   
   Error: "Gene IDs not recognized"
   → Convert to Ensembl or HGNC symbols

3. Try with default parameters first:

   "Run QC with default thresholds"

---

Unexpected results

Symptoms:

• Results don't make biological sense
• Very few/many significant genes
• Clustering doesn't separate conditions

Solutions:

1. Check data quality:

   "Show me QC metrics for my data"
   "What is the batch effect in my samples?"

2. Review parameters:

   "What parameters did you use for clustering?"
   "Can you try with resolution 0.5 instead?"

3. Validate with known markers:

   "Show expression of INS, GCG, and SST across clusters"

---

Account Issues

Can't sign up

Symptoms:

• Sign-up form doesn't submit
• Verification email not received

Solutions:

1. Check email address — Ensure no typos
2. Check spam folder — Verification emails sometimes filtered
3. Try different email — Some domains may be blocked
4. Contact support — support@omics-os.com

---

Forgot password

1. Click "Forgot password" on the login page
2. Enter your email address
3. Check for reset link (including spam folder)
4. If no email received, contact support@omics-os.com

---

Browser Compatibility

Recommended browsers

Known issues

• Safari Private Mode: May have issues with session storage
• Old browsers: Features may not work correctly
• Extensions: Ad blockers can interfere with API calls

---

Getting More Help

If these solutions don't resolve your issue:

1. Include details when contacting support:

   • What you were trying to do
   • The exact error message
   • Your browser and operating system
   • Screenshot if possible

2. Contact channels:

   • Email: support@omics-os.com
   • Response time: 24-48 hours (business days)