Troubleshooting - Futs/kuroibara GitHub Wiki
🐛 Troubleshooting Guide
This guide helps you diagnose and fix common issues with Kuroibara. Start with the most common problems below, then move to specific sections.
🚨 Quick Fixes for Common Issues
🔍 Search Not Working
- Check provider status in Settings → Provider Preferences
- Enable more providers if only a few are selected
- Clear browser cache and refresh the page
- Check internet connection and try again
📚 Can't Add Manga to Library
- Verify you're logged in (check top-right corner)
- Try refreshing the page and searching again
- Check if manga already exists in your library
- Clear browser cache if the issue persists
🖼️ Missing Cover Images
- Wait a few seconds for images to load
- Check your internet connection
- Try a different provider for the same manga
- Disable ad blockers temporarily
🔐 Login Issues
- Check username/password for typos
- Clear browser cookies for the site
- Try incognito/private browsing mode
- Reset password if needed
🔧 Installation & Setup Issues
Docker Problems
Container Won't Start
# Check Docker status
docker --version
docker compose --version
# View container logs
docker compose logs
# Restart containers
docker compose down
docker compose up -d
Port Already in Use
# Find what's using the port
netstat -tulpn | grep :3000
netstat -tulpn | grep :8000
# Change ports in docker-compose.yml
ports:
- "3001:3000" # Change external port
Database Connection Failed
# Check database container
docker compose ps
docker compose logs postgres
# Reset database
docker compose down -v
docker compose up -d
Manual Installation Problems
Python Dependencies Fail
# Upgrade pip
pip install --upgrade pip
# Install with verbose output
pip install -r requirements.txt -v
# Try with --no-cache-dir
pip install --no-cache-dir -r requirements.txt
Node.js Build Fails
# Clear npm cache
npm cache clean --force
# Delete node_modules
rm -rf node_modules package-lock.json
npm install
# Try with different Node version
nvm use 22
npm install
Database Migration Errors
# Check database connection
psql -h localhost -U kuroibara -d kuroibara
# Reset migrations
alembic downgrade base
alembic upgrade head
# Create database if missing
createdb kuroibara
🌐 Provider Issues
No Search Results
- Check provider status in settings
- Try different search terms (alternative spellings)
- Enable more providers for better coverage
- Check provider-specific issues below
Slow Search Performance
- Disable slow providers in preferences
- Limit concurrent searches in settings
- Use favorite providers for faster results
- Clear provider cache if available
Provider-Specific Issues
MangaFox Issues
- Status: Check if fanfox.net is accessible
- Search: Try exact manga titles
- Images: May load slowly, wait a few seconds
MangaBat Issues
- URL: Ensure using mangabats.com (not mangabat.com)
- Search: Use popular manga titles for testing
- Access: Check if site is blocked in your region
Toonily Issues
- NSFW Content: Enable NSFW in settings if needed
- Search: Try manhwa/manhua titles specifically
- Loading: May be slower due to site complexity
📱 User Interface Issues
Page Not Loading
- Refresh the page (Ctrl+F5 or Cmd+Shift+R)
- Clear browser cache and cookies
- Try incognito/private mode
- Check browser console for errors (F12)
Buttons Not Working
- Ensure JavaScript is enabled
- Disable browser extensions temporarily
- Try a different browser
- Check for popup blockers
Mobile Issues
- Use supported browsers (Chrome, Safari, Firefox)
- Enable JavaScript on mobile
- Clear mobile browser cache
- Try desktop version if mobile fails
Dark Mode Problems
- Check theme setting in preferences
- Clear browser cache after theme change
- Refresh page to apply new theme
- Try system theme if custom themes fail
🔐 Authentication & Account Issues
Can't Register
- Check if registration is enabled (admin setting)
- Use valid email format
- Choose unique username
- Check password requirements
Email Verification
- Check spam/junk folder
- Wait up to 10 minutes for email
- Request new verification if needed
- Contact admin if email never arrives
Password Reset
- Use email associated with account
- Check spam folder for reset email
- Link expires in 1 hour - request new one if needed
- Clear browser cache before trying new password
Session Expires Quickly
- Check "Remember Me" when logging in
- Clear browser cookies and log in again
- Check system time is correct
- Contact admin if issue persists
📊 Performance Issues
Slow Loading
- Check internet connection speed
- Close unnecessary browser tabs
- Clear browser cache regularly
- Disable browser extensions temporarily
High Memory Usage
- Close unused tabs
- Restart browser periodically
- Limit concurrent downloads
- Check for memory leaks in browser console
Search Takes Too Long
- Reduce number of enabled providers
- Use more specific search terms
- Check provider response times in settings
- Try searching during off-peak hours
🔍 Debugging Steps
Browser Console Errors
- Open Developer Tools (F12)
- Check Console tab for errors
- Look for red error messages
- Copy error details for support requests
Network Issues
- Check Network tab in Developer Tools
- Look for failed requests (red entries)
- Check response codes (404, 500, etc.)
- Verify API endpoints are accessible
Server Logs
# Docker logs
docker compose logs backend
docker compose logs frontend
# Manual installation logs
tail -f backend/logs/app.log
🆘 Getting Additional Help
Before Asking for Help
- Try the solutions above first
- Check Common Issues page
- Search existing issues
- Gather error details and system information
Information to Include
- Operating System and version
- Browser and version
- Installation method (Docker/Manual)
- Error messages (exact text)
- Steps to reproduce the issue
- Screenshots if helpful
Where to Get Help
- GitHub Issues - Bug reports
- GitHub Discussions - Questions
- Common Issues - Quick solutions
- Installation Guide - Setup help
🔄 Still Having Issues?
If none of these solutions work:
- Create a detailed issue on GitHub
- Include all relevant information listed above
- Be patient - maintainers will respond when available
- Check for updates - your issue might be fixed in newer versions
🧭 Navigation
🏠 Home: Wiki Home
← Previous: Common Issues
→ Next: Performance Optimization
Last updated: December 2024 | Having trouble? Create an issue