Jellycleanarr/TROUBLESHOOTING.md

Troubleshooting Guide - Jellycleanarr TUI

Data Verification ✅

The file jellycleanarr_data_dump.txt contains a complete dump of all API requests and responses.

Key findings:

• ✅ API connection working
• ✅ 12 users found
• ✅ 3 libraries found
• ✅ Playback stats queries working
• ✅ Data formatted correctly for tables

Example data that should display:

HRiggs: 346 plays, 3h 9m watch time
TV: 204 plays, 5d 1h 16m watch time
Landman - s02e05: 13 plays

Issue: Blank TUI

The TUI header, tabs, and footer render, but the content area (tables) is blank.

Fixes Applied

1. API Client - Fixed data format conversion from list-of-lists to dictionaries
2. StatsTable - Moved column initialization to proper lifecycle method
3. CSS - Added explicit height configuration

Things to Try

1. Run with Textual Developer Console

Open two terminals:

Terminal 1:

.venv/Scripts/python.exe -m textual console

Terminal 2:

.venv/Scripts/python.exe -m jellycleanarr

This will show you internal logs and help diagnose rendering issues.

2. Check Terminal Compatibility

Some terminals don't render TUIs properly. Try running in:

• Windows Terminal (recommended)
• PowerShell
• Git Bash
• WSL terminal

3. Verify Data Loading

Run the verification script:

.venv/Scripts/python.exe -c "import asyncio; from src.jellycleanarr.services.stats_service import StatsService; from src.jellycleanarr.api.client import JellyfinClient; from src.jellycleanarr.config import settings; async def test(): c = JellyfinClient(settings.jellyfin_address, settings.jellyfin_api_key); s = StatsService(c); m, l = await s.get_user_stats(limit=3); print(f'Users: {[(u.username, u.total_plays) for u in m]}'); await c.close(); asyncio.run(test())"

4. Try Running with --dev Flag

.venv/Scripts/python.exe -m jellycleanarr --dev

5. Check for Rendering in Specific Area

Try pressing:

• r to refresh
• 1, 2, 3 to switch tabs
• Resize the terminal window

Sometimes TUI elements need a refresh or resize to render properly.

6. Update Textual

Current version: ^0.83.0

Try updating to latest:

uv pip install --upgrade textual

If Still Blank

The data is definitely loading correctly (verified in dump file). The issue is likely:

1. CSS/Layout: Tables exist but are hidden/collapsed
2. Textual Bug: Version-specific rendering issue
3. Terminal: Terminal emulator doesn't support required features

Alternative: Export Data

Since the API is working, you could:

1. Use the dump file for analysis
2. Create a web-based version instead of TUI
3. Export data to CSV/JSON for external viewing

Files for Review

• jellycleanarr_data_dump.txt - Complete API data dump (1590 lines)
• DEBUGGING_NOTES.md - Technical details on fixes applied
• FIXES.md - Summary of all fixes

Contact/Support

If the issue persists, the problem is likely environmental (terminal, Textual version, etc.) rather than with the code logic, since all data fetching and processing is confirmed working.