> ## Documentation Index
> Fetch the complete documentation index at: https://docs.isotopes.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

# Troubleshooting Guide

Solutions to common issues you might encounter while using aidnn.

## Connection Issues

### Can't Log In

**Symptoms:**

* Login page won't load
* Credentials rejected
* Stuck on login screen

**Solutions:**

1. **Check Your URL**
   * Verify you're using the correct aidnn URL
   * Remove any extra characters from the URL

2. **Verify Credentials**
   * Ensure username/email is correct
   * Check caps lock is off
   * Try password reset if unsure

3. **Clear Browser Cache**
   * Clear cookies and cache
   * Try incognito/private browsing mode
   * Try a different browser

4. **Check Network**
   * Verify internet connection
   * Try different network if possible
   * Check if firewall is blocking access

**Still Not Working?**
Contact your system administrator or [support@isotopes.ai](mailto:support@isotopes.ai)

### Data Source Connection Failed

**Symptoms:**

* "Connection failed" error
* Can't connect to database
* Business app authentication fails

**Solutions:**

**For Database Connections:**

1. Verify connection details are correct:
   * Host/server address
   * Port number
   * Database name
   * Username and password

2. Check permissions:
   * User has read access
   * Can connect remotely
   * No IP restrictions blocking access

3. Test from another tool:
   * Verify database is accessible
   * Confirm credentials work elsewhere

**For Business App Connections:**

1. Re-authenticate:
   * Go to Data Sources
   * Click "Reconnect"
   * Complete authorization flow

2. Check account status:
   * Verify account is active
   * Confirm you have necessary permissions
   * Check if subscription is current

**For Google Drive:**

1. Refresh authorization:
   * Disconnect and reconnect
   * Grant all requested permissions

2. Check Google account:
   * Logged into correct account
   * Account has Drive access
   * Not blocked by organization policy

## File Upload Issues

### Upload Fails

**Symptoms:**

* File won't upload
* Upload stops partway
* "Upload failed" error

**Common Causes & Solutions:**

**File Too Large:**

* Maximum size is 100MB
* Split file or use Google Drive for larger files
* Use database connection for very large datasets

**Unsupported Format:**

* Check file format is supported (CSV, Excel, JSON, etc.)
* Try re-exporting from source application
* Convert to CSV if possible

**File Corrupted:**

* Try opening file in Excel/editor
* Re-export from source system
* Check file isn't password-protected

**Network Issues:**

* Check internet connection
* Try again with stable connection
* Try smaller test file first

### File Uploaded But Won't Process

**Symptoms:**

* Upload completes but aidnn can't read it
* "Error processing file" message

**Solutions:**

1. **Check File Structure:**
   * First row should be headers
   * Consistent number of columns per row
   * No completely empty rows at start

2. **Check Encoding:**
   * Save as UTF-8 if possible
   * Try different encoding options

3. **Simplify File:**
   * Remove unnecessary formatting
   * Remove merged cells (Excel)
   * Remove macros or embedded objects

4. **Try Different Format:**
   * If Excel, try saving as CSV
   * Remove extra sheets if multi-sheet workbook

## Analysis Issues

### Plan Seems Wrong

**Symptoms:**

* Plan doesn't match your request
* Steps don't make sense
* Wrong data source referenced

**Solutions:**

1. **Review Your Question:**
   * Was it clear and specific?
   * Did you mention the right data?
   * Is time period specified?

2. **Ask for Clarification:**
   > "Why are you using approach X?"
   > "Should step 3 be doing Y instead?"

3. **Request Modifications:**
   > "Change step 2 to use revenue column instead"
   > "Use my QuickBooks data instead of the CSV"

4. **Start Over:**
   * Cancel the plan
   * Rephrase your question more clearly
   * Break into smaller steps

### Results Don't Look Right

**Symptoms:**

* Numbers seem incorrect
* Missing expected data
* Charts look wrong

**Solutions:**

1. **Verify Data Source:**
   * Check correct file/table was used
   * Verify date range
   * Confirm filters didn't exclude data

2. **Check the Plan:**
   * Review what steps were executed
   * Verify calculations were correct
   * Check for filtering or aggregation issues

3. **Validate Against Known Values:**
   * Compare to known totals
   * Check a few records manually
   * Verify calculations make sense

4. **Ask aidnn:**
   > "Show me how you calculated this total"
   > "What data was included in this analysis?"
   > "Why is the count different from what I expected?"

### Analysis Takes Too Long

**Symptoms:**

* Queries running for many minutes
* Session seems frozen
* Waiting indefinitely

**Solutions:**

1. **For Large Datasets:**
   * Filter to smaller date ranges
   * Limit to specific categories
   * Sample the data first

2. **For Database Queries:**
   * Check database performance
   * Ensure queries are optimized
   * Verify indexes exist on key columns

3. **Break It Down:**
   * Split complex analysis into steps
   * Do exploratory analysis on subset
   * Scale up once approach is validated

4. **Check Status:**
   * Look for progress indicators
   * Refresh page if truly stuck
   * Contact support if persistent

### aidnn Doesn't Understand

**Symptoms:**

* Irrelevant plans
* "I don't understand" messages
* Wrong interpretation

**Solutions:**

1. **Simplify Your Question:**
   * Use plain language
   * Avoid jargon or acronyms
   * Be more explicit

2. **Provide More Context:**
   * Specify which data
   * Mention column names
   * Give examples

3. **Break It Down:**
   * Ask one thing at a time
   * Build up complex analysis step-by-step
   * Reference previous results

4. **Use Different Phrasing:**
   * Try asking the same thing different ways
   * Describe what output you want
   * Show an example

## Visualization Issues

### Chart Looks Wrong

**Symptoms:**

* Chart type inappropriate
* Axis labels unclear
* Too much/too little data

**Solutions:**

1. **Request Different Chart Type:**
   > "Show this as a line chart instead"
   > "Make it a bar chart"

2. **Adjust Data:**
   > "Show only top 10 categories"
   > "Filter to last 6 months"
   > "Remove outliers"

3. **Fix Axes:**
   > "Use logarithmic scale"
   > "Change the Y-axis to show percentages"

### Can't See Chart Elements

**Symptoms:**

* Labels cut off
* Legend missing
* Too small to read

**Solutions:**

1. **Resize:**
   * Make browser window larger
   * Zoom in on chart
   * Download as image at higher resolution

2. **Simplify:**
   > "Show fewer categories"
   > "Group smaller categories into 'Other'"

3. **Request Adjustments:**
   > "Make labels more readable"
   > "Rotate X-axis labels"

## Session Issues

### Can't Find Previous Session

**Symptoms:**

* Session missing from list
* Can't locate by name

**Solutions:**

1. **Use Search:**
   * Search by session name
   * Search by keywords in conversation
   * Filter by date range

2. **Check Archives:**
   * Look in archived sessions
   * Filter to show archived

3. **Check Shared:**
   * Look in shared sessions section
   * Verify it wasn't accidentally shared

### Session Won't Load

**Symptoms:**

* Session opens but shows error
* Infinite loading
* Partial content loads

**Solutions:**

1. **Refresh Page:**
   * Simple refresh often works
   * Try hard refresh (Ctrl+F5)

2. **Clear Cache:**
   * Clear browser cache
   * Try incognito mode

3. **Check Data Sources:**
   * Verify data sources still connected
   * Reconnect if needed

4. **Try Different Browser:**
   * Test in Chrome, Firefox, Safari
   * Update browser if outdated

### Lost Work

**Symptoms:**

* Session appears empty
* Recent work missing
* Changes not saved

**Solutions:**

1. **Check Auto-Save:**
   * Sessions auto-save continuously
   * Refresh to see latest

2. **Verify Session:**
   * Make sure you're in correct session
   * Check session timestamp

3. **Check Network:**
   * Network interruption during save
   * Retry operations if needed

**Prevention:**

* Name sessions immediately
* Export important results
* Don't rely solely on sessions for critical work

## Performance Issues

### Slow Response Times

**Symptoms:**

* Long delays between messages
* Slow plan generation
* Laggy interface

**Solutions:**

1. **Check Internet:**
   * Test internet speed
   * Switch networks if possible
   * Close other bandwidth-heavy apps

2. **Browser Performance:**
   * Close unused tabs
   * Clear cache
   * Restart browser
   * Update to latest version

3. **Simplify Requests:**
   * Work with smaller data subsets
   * Break complex analysis into steps
   * Filter data before complex operations

### Browser Crashes

**Symptoms:**

* Browser freezes
* Tab crashes
* Memory errors

**Solutions:**

1. **Reduce Memory Usage:**
   * Close other tabs
   * Restart browser
   * Clear cache

2. **Update Browser:**
   * Ensure browser is current
   * Try different browser

3. **Work Smaller:**
   * Filter data to smaller sets
   * Download large results rather than viewing inline
   * Break analysis into smaller sessions

## Data Quality Issues

### Missing or Null Values

**Symptoms:**

* Unexpected null/blank values
* Calculations seem off
* Records missing

**Solutions:**

1. **Identify Missing Data:**
   > "Check for missing values"
   > "Show me rows with null revenue"

2. **Handle Missing Data:**
   > "Remove rows with missing values"
   > "Fill missing prices with average"
   > "Replace nulls with 0"

3. **Investigate Source:**
   * Check source data
   * Verify data extraction
   * Fix at source if possible

### Duplicate Records

**Symptoms:**

* Counts higher than expected
* Same record appears multiple times

**Solutions:**

1. **Check for Duplicates:**
   > "Find duplicate rows"
   > "Show me potential duplicate customers"

2. **Remove Duplicates:**
   > "Remove duplicate rows"
   > "Keep only one record per customer ID"

3. **Understand Why:**
   * Check data source
   * Verify join logic
   * Fix source process if recurring

### Incorrect Data Types

**Symptoms:**

* Numbers treated as text
* Dates not recognized
* Can't perform calculations

**Solutions:**

1. **Convert Data Types:**
   > "Convert amount column to numbers"
   > "Parse date column as dates"

2. **Fix Formatting:**
   > "Remove \$ and commas from prices"
   > "Standardize date format"

## Getting Additional Help

### Before Contacting Support

Gather this information:

* What you were trying to do
* Exact error message (screenshot if possible)
* Steps to reproduce the issue
* Your session ID (if applicable)
* When the issue started

### How to Contact Support

📧 **Email**: [support@isotopes.ai](mailto:support@isotopes.ai)

Include:

* Detailed description of issue
* Steps you've already tried
* Attachments (screenshots, error messages)
* Your account information
* Urgency level

### Emergency Issues

For critical issues affecting multiple users:

* Email [support@isotopes.ai](mailto:support@isotopes.ai) with "URGENT" in subject
* Contact your account administrator
* Check status page (if available) for known issues

## Quick Reference

| Issue            | First Step                               |
| ---------------- | ---------------------------------------- |
| Can't log in     | Clear cache, try different browser       |
| Upload fails     | Check file size (under 100MB) and format |
| Connection error | Verify credentials, check permissions    |
| Wrong results    | Review plan, check data source           |
| aidnn confused   | Rephrase question more simply            |
| Session missing  | Use search, check archives               |
| Analysis slow    | Filter to smaller dataset                |
| Chart wrong      | Request different chart type             |

## Additional Resources

* **[FAQ](./faq)** - Common questions answered
* **[Best Practices](../best-practices/asking-questions)** - Get better results
* **[Getting Started](../getting-started/welcome)** - Basics guide
* **Support**: [support@isotopes.ai](mailto:support@isotopes.ai)

Most issues can be resolved quickly with these troubleshooting steps. If you're still stuck, we're here to help!