Troubleshooting & FAQ¶

Table of Contents¶

Introduction
Project Structure
Core Components
Architecture Overview
Detailed Component Analysis
Dependency Analysis
Performance Considerations
Troubleshooting Guide
Monitoring and Alerting
Recovery Procedures
Frequently Asked Questions
Conclusion

Introduction¶

This document provides comprehensive troubleshooting guidance for Nexo, covering installation problems, configuration errors, performance issues, debugging techniques, monitoring and alerting setup, recovery procedures, and frequently asked questions. It is designed to help both new users and experienced operators diagnose and resolve issues quickly.

Project Structure¶

Nexo consists of: - A FastAPI-based backend service under apps/service with routes, core processing logic, API integrations, and shared configuration/database utilities. - A React dashboard under apps/dashboard (v2) and a legacy v1 backup under apps/dashboard-v1-backup. - Database migrations via Alembic. - Cache files for decisions, history, Jellyfin state, and status. - Entry points and build/release scripts at the repository root.

graph TB
subgraph "Backend Service"
S_APP["apps/service/app.py"]
S_MAIN["apps/service/main.py"]
S_DEPS["apps/service/deps.py"]
S_CONF["apps/shared/config.py"]
S_DB["apps/shared/db.py"]
S_ROUTES["apps/service/routes/*"]
S_CORE["apps/service/core/*"]
S_API["apps/service/api/*"]
end
subgraph "Dashboard"
D_V2["apps/dashboard/src/*"]
D_V1["apps/dashboard-v1-backup/src/*"]
end
subgraph "Data"
C_DEC["cache/decisions.json"]
C_HIS["cache/history.json"]
C_JF["cache/jellyfin_state.json"]
C_STAT["cache/status.json"]
end
S_MAIN --> S_APP
S_APP --> S_ROUTES
S_ROUTES --> S_CORE
S_ROUTES --> S_API
S_APP --> S_DB
S_APP --> S_CONF
S_APP --> S_DEPS
D_V2 --> S_APP
D_V1 --> S_APP
S_CORE --> C_DEC
S_CORE --> C_HIS
S_CORE --> C_JF
S_CORE --> C_STAT

Diagram sources - apps/service/app.py - apps/service/main.py - apps/shared/config.py - apps/shared/db.py - apps/service/routes/jellyfin.py - apps/service/core/scan.py - apps/service/core/pipeline.py - apps/service/core/matcher.py - apps/service/core/confidence.py - apps/service/api/tmdb.py - apps/service/api/tmdb_index.py - apps/service/api/ai.py - cache/decisions.json - cache/history.json - cache/jellyfin_state.json - cache/status.json

Section sources - README.md - apps/service/app.py - apps/service/main.py - apps/shared/config.py - apps/shared/db.py

Core Components¶

Backend application entrypoint and router registration.
Shared configuration loader and database session management.
Routes for authentication, configuration, media server integration, logs, status, tools, push notifications, and history.
Core scanning, pipeline orchestration, matching, and confidence scoring.
External API integrations (TMDB, AI).
Dashboard UIs (v2 React and v1 backup) that call backend endpoints.

Key responsibilities: - Configuration: centralized settings for DB, TMDB, Jellyfin, logging, and runtime options. - Data persistence: database models and sessions; JSON cache for transient or derived data. - Processing: file scanning, metadata enrichment, decision-making, and indexing. - Integration: Jellyfin sync and external APIs.

Section sources - apps/service/app.py - apps/service/main.py - apps/shared/config.py - apps/shared/db.py - apps/service/routes/jellyfin.py - apps/service/core/scan.py - apps/service/core/pipeline.py - apps/service/core/matcher.py - apps/service/core/confidence.py - apps/service/api/tmdb.py - apps/service/api/tmdb_index.py - apps/service/api/ai.py

Architecture Overview¶

The system exposes REST endpoints from the FastAPI app. The dashboard consumes these endpoints. Core processing pipelines coordinate scanning, parsing, matching, and decision storage. External services include TMDB and optional AI providers. Jellyfin integration allows synchronization of media metadata.

sequenceDiagram
participant User as "User"
participant DashV2 as "Dashboard v2"
participant API as "FastAPI App"
participant Router as "Routes"
participant Core as "Core Pipeline"
participant DB as "Database"
participant Cache as "JSON Cache"
participant Ext as "TMDB/AI/Jellyfin"
User->>DashV2 : Open dashboard
DashV2->>API : GET /api/status
API->>Router : Dispatch route
Router->>Core : Read status/scans
Core->>Cache : Load decisions/history
Core-->>Router : Status summary
Router-->>API : JSON response
API-->>DashV2 : Status payload
Note over API,Ext : External calls occur during scans/indexing

Diagram sources - apps/service/app.py - apps/service/routes/status.py - apps/service/core/pipeline.py - apps/service/core/scan.py - cache/decisions.json - cache/history.json - apps/service/api/tmdb.py - apps/service/api/ai.py - apps/service/routes/jellyfin.py

Detailed Component Analysis¶

Installation and Environment¶

Common issues: - Python version mismatch or missing dependencies. - Permission errors when writing to directories or installing packages globally. - Platform-specific binaries (e.g., Playwright browsers) failing to install.

Resolution steps: - Use a virtual environment and install requirements from the project’s dependency list. - Ensure write permissions for cache and log directories. - For Windows/macOS/Linux, follow platform notes for browser drivers if using headless browsing features.

Operational checks: - Verify the service starts without import errors. - Confirm database initialization and migration success.

Section sources - requirements.txt - setup.py - apps/service/main.py - apps/service/app.py - start_chrome.py - video_downloader_playwright.py

Configuration Errors¶

Symptoms: - Service fails to start due to invalid config keys or missing values. - Database connection failures. - TMDB or Jellyfin endpoints not reachable.

Resolution steps: - Validate all required configuration entries exist and are correctly formatted. - Test database connectivity and ensure the schema is up-to-date. - Verify network access to external APIs and correct base URLs.

Configuration hotspots: - Centralized configuration loader. - Database session factory and connection string. - Route handlers that read settings for TMDB/Jellyfin.

Section sources - apps/shared/config.py - apps/shared/db.py - apps/service/routes/config.py - apps/service/api/tmdb.py - apps/service/routes/jellyfin.py

Database Connection Issues¶

Symptoms: - “Cannot connect to database” or “No such table” errors. - Migration failures or stale schema.

Resolution steps: - Check connection string and credentials. - Run Alembic migrations explicitly. - Inspect database logs for lock contention or permission issues.

Migration references: - Initial schema and subsequent versions.

Section sources - apps/shared/db.py - alembic.ini - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py

API Endpoint Misconfigurations¶

Symptoms: - Dashboard shows empty data or errors on load. - Authentication failures. - Push notification subscriptions not working.

Resolution steps: - Confirm endpoint paths and CORS settings. - Validate user roles and token handling. - Check push subscription storage and delivery.

Endpoints to verify: - Authentication, users, configuration, logs, status, history, tools, push, Jellyfin.

Section sources - apps/service/routes/auth.py - apps/service/routes/users.py - apps/service/routes/config.py - apps/service/routes/logs.py - apps/service/routes/status.py - apps/service/routes/history.py - apps/service/routes/tools.py - apps/service/routes/push.py - apps/dashboard/src/pages/Login.tsx - apps/dashboard/src/pages/Config.tsx - apps/dashboard/src/pages/Logs.tsx - apps/dashboard/src/pages/Home.tsx - apps/dashboard/src/pages/Historico.tsx - apps/dashboard/src/pages/Decidir.tsx - apps/dashboard/src/pages/Usuarios.tsx

Media Server Integration Problems¶

Symptoms: - Jellyfin sync does not update libraries. - State drift between local cache and Jellyfin.

Resolution steps: - Verify Jellyfin URL, API key, and library IDs. - Clear cached Jellyfin state and re-sync. - Inspect logs for HTTP errors or timeouts.

Section sources - apps/service/routes/jellyfin.py - cache/jellyfin_state.json - clear_jellyfin.py - apps/dashboard/src/pages/MediaServer.tsx

Performance Issues¶

Symptoms: - Slow file scanning. - High CPU usage during indexing. - Memory growth over time.

Root causes and remedies: - Large directory trees and heavy metadata extraction. - Excessive parallelism without resource limits. - Inefficient matching or confidence calculations.

Optimization recommendations: - Tune concurrency and batch sizes in scanning and pipeline. - Limit recursive depth and filter file types early. - Cache intermediate results and avoid redundant I/O. - Profile CPU/memory hotspots in matcher and confidence modules.

Section sources - apps/service/core/scan.py - apps/service/core/pipeline.py - apps/service/core/matcher.py - apps/service/core/confidence.py - cache/decisions.json - cache/history.json

Debugging and Diagnostics¶

Guidance: - Enable detailed logging and capture request/response traces. - Use status and logs endpoints to inspect current state and recent events. - Review dashboard pages for real-time insights.

Diagnostic flows: - Logs retrieval and filtering. - Status polling and health checks. - Tools for manual operations and diagnostics.

Section sources - apps/service/routes/logs.py - apps/service/routes/status.py - apps/service/routes/tools.py - apps/dashboard/src/pages/Logs.tsx - apps/dashboard/src/pages/Home.tsx

Dependency Analysis¶

External dependencies and integrations: - Python packages listed in requirements. - TMDB API client and optional AI provider. - Browser automation for video downloading (optional). - Build and release tooling.

graph LR
REQ["requirements.txt"]
SETUP["setup.py"]
TMDB["apps/service/api/tmdb.py"]
AI["apps/service/api/ai.py"]
TIDX["apps/service/api/tmdb_index.py"]
DL_SIMPLE["video_downloader_simple.py"]
DL_PW["video_downloader_playwright.py"]
DL_CK["video_downloader_cookies.py"]
CHROME["start_chrome.py"]
BUILD["build.py"]
REL["release.py"]
REQ --> TMDB
REQ --> AI
REQ --> TIDX
DL_PW --> CHROME
DL_CK --> DL_PW
DL_SIMPLE --> DL_PW
BUILD --> SETUP
REL --> BUILD

Diagram sources - requirements.txt - setup.py - apps/service/api/tmdb.py - apps/service/api/ai.py - apps/service/api/tmdb_index.py - video_downloader_simple.py - video_downloader_playwright.py - video_downloader_cookies.py - start_chrome.py - build.py - release.py

Section sources - requirements.txt - setup.py - apps/service/api/tmdb.py - apps/service/api/ai.py - apps/service/api/tmdb_index.py - video_downloader_playwright.py - start_chrome.py - build.py - release.py

Performance Considerations¶

Scan tuning: adjust recursion depth, file filters, and worker pools.
Matching optimization: pre-filter candidates and use indexes where possible.
Confidence thresholds: raise thresholds to reduce churn and unnecessary writes.
Resource limits: cap memory usage and enforce timeouts for external calls.
Caching strategy: persist intermediate results to reduce repeated work.

[No sources needed since this section provides general guidance]

Troubleshooting Guide¶

Installation Problems¶

Dependency conflicts: isolate environments and pin versions from requirements.
Permission issues: run with appropriate user privileges or change ownership of target directories.
Platform-specific issues: install platform wheels or browser binaries as needed.

Section sources - requirements.txt - setup.py - start_chrome.py - video_downloader_playwright.py

Configuration Errors¶

Validate configuration keys and values.
Test database connectivity and migrations.
Verify external API endpoints and credentials.

Section sources - apps/shared/config.py - apps/shared/db.py - apps/service/routes/config.py - apps/service/api/tmdb.py - apps/service/routes/jellyfin.py

Database Connection Issues¶

Check connection strings and credentials.
Run migrations explicitly.
Inspect database logs for locks or permissions.

Section sources - apps/shared/db.py - alembic.ini - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py

API Endpoint Misconfigurations¶

Confirm routes are registered and accessible.
Validate authentication and authorization flows.
Check push notification subscriptions and SSE connections.

Section sources - apps/service/app.py - apps/service/routes/auth.py - apps/service/routes/users.py - apps/service/routes/push.py - apps/dashboard-v1-backup/src/services/api.js - apps/dashboard-v1-backup/src/services/sse.js

Media Server Integration Problems¶

Validate Jellyfin URL, API key, and library IDs.
Clear Jellyfin state cache and retry sync.
Inspect logs for HTTP errors.

Section sources - apps/service/routes/jellyfin.py - cache/jellyfin_state.json - clear_jellyfin.py

Performance Issues¶

Slow scanning: tune concurrency and filters.
High CPU: profile matcher and confidence modules.
Memory leaks: monitor cache growth and process restarts.

Section sources - apps/service/core/scan.py - apps/service/core/pipeline.py - apps/service/core/matcher.py - apps/service/core/confidence.py - cache/decisions.json - cache/history.json

Debugging Guides¶

Analyze logs via logs endpoint and dashboard.
Use status endpoint to check health and recent activity.
Leverage tools endpoint for manual operations.

Section sources - apps/service/routes/logs.py - apps/service/routes/status.py - apps/service/routes/tools.py - apps/dashboard/src/pages/Logs.tsx - apps/dashboard/src/pages/Home.tsx

Monitoring and Alerting¶

Health checks: poll status endpoint periodically.
Log aggregation: forward logs to a central system and set alerts for error spikes.
Metrics: track scan durations, match counts, and external API latency.
Alerts: configure thresholds for failed requests, high CPU, and memory growth.

[No sources needed since this section provides general guidance]

Recovery Procedures¶

Corrupted Data¶

Back up cache files before making changes.
Reset Jellyfin state and re-sync.
Rebuild decisions/history by re-running scans.

Section sources - cache/decisions.json - cache/history.json - cache/jellyfin_state.json - clear_jellyfin.py

Failed Migrations¶

Roll back to a known good migration.
Re-run migrations after fixing schema issues.
Verify tables and constraints post-migration.

Section sources - alembic.ini - alembic/versions/001_initial_schema.py - alembic/versions/002_add_decision_type.py

Service Crashes¶

Restart the service and review crash logs.
Check for unhandled exceptions in routes and core modules.
Validate configuration and external dependencies.

Section sources - apps/service/main.py - apps/service/app.py - apps/service/routes/logs.py

Frequently Asked Questions¶

Why is scanning slow?
Reduce recursion depth, limit file types, and tune concurrency.
How do I reset Jellyfin integration?
Clear jellyfin_state.json and reconfigure credentials.
What should I do if the dashboard cannot connect?
Verify backend URL, CORS, and authentication settings.
How can I improve matching accuracy?
Adjust confidence thresholds and refine candidate filters.
Where are logs stored and how do I view them?
Use the logs endpoint and dashboard logs page.

[No sources needed since this section summarizes common scenarios]

Conclusion¶

Use this guide to systematically diagnose and resolve installation, configuration, performance, and integration issues. Combine logging, status checks, and targeted recovery actions to maintain a healthy Nexo deployment.