gh-christianlouis-docuelevate/docs/Troubleshooting.md

Troubleshooting Guide

This document provides solutions to common problems encountered when using DocuElevate.

Common Issues

Application Won't Start

Symptoms

• Docker containers exit immediately
• Web interface not accessible
• Error logs show startup failures

Possible Solutions

1. Check environment variables

   docker-compose config
   

   Ensure all required variables are set properly in your .env file.

2. Verify permissions

   ls -la /path/to/workdir
   

   Make sure the application has write permissions to the working directory.

3. Check port availability

   netstat -tuln | grep 8000
   

   Ensure the port isn't already in use by another application.

Document Upload Fails

Symptoms

• Error messages during upload
• Files appear to upload but aren't processed
• Browser console errors

Possible Solutions

1. Check file size limits

   • Default maximum file size is 100MB
   • Adjust client_max_body_size in your reverse proxy configuration

2. Verify storage space

   df -h
   

   Ensure there's sufficient disk space available.

3. Check worker process

   docker-compose logs worker
   

   Verify the Celery worker is running and processing tasks.

OCR or Text Extraction Issues

Symptoms

• Documents upload but text isn't extracted
• Poor quality text extraction
• API errors related to Azure services

Possible Solutions

1. Verify API credentials Check the Azure Document Intelligence API key and endpoint in your .env file.

2. Check document quality

   • Ensure documents are clearly scanned
   • Try preprocessing images to improve quality before upload

3. Test API connectivity

   curl -X GET -H "Ocp-Apim-Subscription-Key: YOUR_KEY" "YOUR_ENDPOINT"
   

   Ensure the API is accessible from your server.

Email Integration Problems

Symptoms

• Email attachments aren't being processed
• IMAP connection errors in logs
• Authentication failures

Possible Solutions

1. Verify IMAP settings Check host, port, username, and password in your configuration.

2. Test IMAP connectivity

   telnet mail.example.com 993
   

   Ensure the IMAP server is accessible.

3. Enable less secure apps For Gmail and some providers, you may need to enable access for less secure apps or use app-specific passwords.

4. Check firewall settings Ensure your server can make outbound connections to the mail server.

Storage Integration Issues

Symptoms

• Files aren't appearing in Dropbox/Nextcloud/Paperless
• Authentication errors in logs
• API rate limiting errors

Possible Solutions

1. Verify API credentials Double-check all API keys, tokens, and secrets.

2. Check access permissions Ensure the application has write permissions to the specified folders.

3. Refresh tokens For OAuth-based services like Dropbox, try generating new refresh tokens.

4. Examine detailed logs

   docker-compose logs worker | grep -i dropbox
   

   Look for specific error messages related to the service.

Database Issues

Symptoms

• Application errors related to database connections
• Missing or corrupt data
• Slow performance

Possible Solutions

1. Check database connection string Verify the DATABASE_URL variable in your .env file.

2. Inspect database integrity

   sqlite3 database.db "PRAGMA integrity_check;"
   

   (For SQLite databases)

3. Perform database migrations

   docker-compose exec api alembic upgrade head
   

   Ensure the database schema is up-to-date.

Authentication Problems

Symptoms

• Unable to log in
• Redirect loops during authentication
• OAuth errors

Possible Solutions

1. Verify Authentik configuration Check client ID, client secret, and configuration URL.

2. Check callback URLs Ensure the redirect URIs are correctly configured in your OAuth provider.

3. Clear browser cookies and cache Authentication issues can sometimes be resolved by clearing browser data.

Getting Additional Help

If you continue to experience issues after trying these solutions:

1. Check the logs for detailed error messages

   docker-compose logs --tail=100
   

2. Open an issue on the GitHub repository

3. Contact the developer via the information provided on the About page