fiftyone-troubleshoot

What this skill does

# FiftyOne Troubleshoot

## Overview

Diagnose and fix common FiftyOne pain points. Match the user's symptom to the [Issue Index](#issue-index), explain the root cause and proposed fix, get approval, then apply.

> Shell commands in this skill are written for macOS/Linux. On Windows (non-WSL), adapt using PowerShell equivalents or use WSL.

Designed to grow: add new issues at the bottom as they are encountered.

## Prerequisites

- FiftyOne installed: `pip install fiftyone`
- MCP server running (optional, for plugin-related fixes)

## Key Directives

### 1. Always explain, propose, and confirm before acting
**NEVER run a fix without first:**
1. Explaining what is wrong and why
2. Describing what the fix will do
3. Asking the user to confirm: *"Should I apply this fix?"*

Wait for explicit user confirmation before executing anything that modifies files, config, or data.

### 2. Never touch user datasets — FiftyOne is the source of truth
- Except when given explicit and direct instructions by the user:
    - NEVER modify, edit, delete, or clone user datasets as part of troubleshooting
    - NEVER call `fo.delete_dataset()`
    - NEVER truncate, wipe, or alter dataset contents or sample fields to diagnose an issue
- Use FiftyOne's read-only API to inspect state: `fo.list_datasets()`, `fo.load_dataset()`, `len(dataset)`, `dataset.get_field_schema()` — these are safe
- FiftyOne's state (datasets, fields, brain runs) is the ground truth; read it, never rewrite it to "fix" a problem

### 3. Never directly manipulate MongoDB
- NEVER use `pymongo`, `db.drop_collection()`, or raw MongoDB shell commands
- All data operations must go through the FiftyOne Python API

### 4. Never modify config or files silently
- NEVER change `database_uri`, `database_name`, or any config file without showing what will change and getting approval
- NEVER append to shell profiles (`.zshrc`, `.bash_profile`, virtualenv `activate`) without showing the exact line change and getting explicit user confirmation to apply

### 5. Restart processes after env / config changes
Any fix that sets an environment variable or modifies a config file only takes effect for **new** processes. Already-running App servers, service managers, and Python scripts will NOT pick up the change.
- After setting `FIFTYONE_DATABASE_NAME` or similar env vars, identify and restart any running FiftyOne processes
- Check with: `ps aux | grep fiftyone`
- Stop stale processes: `pkill -f "fiftyone"` (confirm with user first)

### 6. Always verify after fixing
Run the [Health Check](#health-check) after every fix to confirm the environment is operational.

---

## Workflow

1. **Diagnose** — run the Diagnostic Quick-Check
2. **Explain** — describe the root cause in plain language
3. **Propose** — show the fix and what it will change
4. **Confirm** — ask the user: *"Should I apply this?"*
5. **Execute** — apply the fix only after approval
6. **Verify** — run the Health Check

---

## Diagnostic Quick-Check

Handles connection failures gracefully — always produce useful output:

```python
import sys

print(f"Python:  {sys.executable}")
print(f"Version: {sys.version.split()[0]}")

try:
    import fiftyone as fo
    print(f"FiftyOne: {fo.__version__}")
    print(f"Database: {fo.config.database_name}")
    print(f"DB URI:   {fo.config.database_uri or '(internal MongoDB)'}")
except ImportError:
    print("ERROR: fiftyone not installed — check Python environment, if needed run: pip install fiftyone")
    sys.exit(1)

try:
    print(f"Datasets: {fo.list_datasets()}")
    print("Connection: OK")
except Exception as e:
    print(f"Connection ERROR: {e}")
    print("→ Match this error to the Issue Index below")
```

---

## Health Check

Run after any fix to confirm the environment is fully operational.

> This script creates and destroys a **temporary test dataset** (`_fo_health_check`). It does not touch any user datasets. Do not manually create a dataset with the name "_fo_health_check".

```python
import fiftyone as fo
import tempfile, os

TEST_NAME = "_fo_health_check"

try:
    # Clean up any debris from a previous failed check
    if TEST_NAME in fo.list_datasets():
        fo.delete_dataset(TEST_NAME)

    # Non-persistent: auto-removed if Python exits before cleanup
    dataset = fo.Dataset(TEST_NAME, persistent=False)
    dataset.add_sample(fo.Sample(
        filepath=os.path.join(tempfile.gettempdir(), "health_check.jpg")
    ))
    assert len(dataset) == 1, "Sample write failed"

    # Verify connection round-trip
    assert TEST_NAME in fo.list_datasets(), "Dataset not listed"

    print(f"OK — FiftyOne {fo.__version__} on database '{fo.config.database_name}'")

finally:
    # Always clean up, even on failure
    if TEST_NAME in fo.list_datasets():
        fo.delete_dataset(TEST_NAME)
```

---

## Issue Index

| Symptom | Section |
|---------|---------|
| Dataset disappeared after restart | [Dataset Persistence](#issue-dataset-disappeared) |
| App won't open / not connected | [App Connection](#issue-app-wont-open) |
| Changes not saved | [Unsaved Changes](#issue-changes-not-saved) |
| Video not playing / codec error | [Video Codec](#issue-video-codec) |
| Too many open files (macOS) | [Open Files Limit](#issue-too-many-open-files-macos) |
| App not loading in notebook / remote | [Notebook / Remote](#issue-app-not-loading-in-notebook-or-remote) |
| Plots not showing in notebook | [Notebook Plots](#issue-plots-not-appearing-in-notebook) |
| MongoDB connection failure | [MongoDB](#issue-mongodb-connection-error) |
| Operator not found / plugin missing | [Missing Plugin](#issue-operator-not-found) |
| "No executor available" | [Delegated Operators](#issue-no-executor-available) |
| Dataset is read-only | [Read-Only Dataset](#issue-dataset-is-read-only) |
| Slow performance on large datasets | [Performance](#issue-slow-performance) |
| App showing stale / wrong data | [Stale Data](#issue-stale-app-data) |
| Downgrading FiftyOne | [Downgrading](#issue-downgrading-fiftyone) |
| Database version mismatch | [DB Version Mismatch](#issue-database-version-mismatch) |
| Teams / OSS client type mismatch | [Teams vs OSS](#issue-fiftyone-teams-vs-oss-type-mismatch) |

---

## Issue: Dataset Disappeared

**Cause:** Datasets are non-persistent by default and are deleted when Python exits.

**Fix:**
```python
import fiftyone as fo

# Make an existing dataset persistent
dataset = fo.load_dataset("my-dataset")
dataset.persistent = True

# Prevention: always create persistent datasets
dataset = fo.Dataset("my-dataset", persistent=True)
```

> If the dataset is already gone from `fo.list_datasets()`, it cannot be recovered through FiftyOne — re-import from source files.

---

## Issue: App Won't Open

**Cause A — Script exits before the App loads.** Fix: add `session.wait()`.
```python
session = fo.launch_app(dataset)
session.wait()  # keeps the process alive
```

**Cause B — Windows multiprocessing.** Fix: add the `__main__` guard.
```python
if __name__ == "__main__":
    session = fo.launch_app(dataset)
    session.wait()
```

**Cause C — Port already in use.**
```python
session = fo.launch_app(dataset, port=<alternative-port>)  # e.g. 5152, 5153
```

**Cause D — Stale process.**
```bash
pkill -f "fiftyone"
```

---

## Issue: Changes Not Saved

**Fix — sample edits:**
```python
sample["my_field"] = "new_value"
sample.save()  # required
```

**Fix — dataset-level properties:**
```python
dataset.info["description"] = "Updated"
dataset.save()  # required
```

**Fix — bulk updates (no `.save()` needed):**
```python
dataset.set_values("my_field", [v1, v2, ...])
```

---

## Issue: Video Codec

**Cause:** Video codec not supported by the browser's HTML5 player (requires MP4/H.264, WebM, or Ogg).

> ⚠️ Re-encoding **overwrites files on disk**. Show the user the exact paths that will be modified and get explicit confirmation before running.

```python
import fiftyone.utils.video as fouv

# Re-encode all videos in a dataset
fouv.reencode_video