Appearance
Common Issues
This page covers general troubleshooting for GhostAI. For PII-specific issues, see False Positives and Performance.
Models Not Loading
Symptoms
- "Loading models..." spinner that never completes
- Image model selector stuck on loading
- NER model unavailable errors in the backend log
Causes and Fixes
Docker image missing model downloads:
Models should be pre-downloaded during Docker build. If the build skipped this step:
bash
# Verify models are present in the container
docker exec <container> python -c "from transformers import pipeline; p = pipeline('token-classification', model='dymium/Dymium-NER-v1'); print('OK')"If this fails, rebuild with the full Dockerfile that includes the model download step.
Insufficient memory:
Transformer models require significant RAM:
| Model | Memory |
|---|---|
| Dymium NER (PII detection) | ~800 MB |
| Clinical NER (healthcare) | ~500 MB |
| CLIP (image intelligence) | ~400 MB |
Ensure the container has at least 4 GB of available memory. If running multiple models (e.g., healthcare vertical with clinical NER), allocate 6+ GB.
React Strict Mode (development only):
In development, React 18 Strict Mode mounts and unmounts components twice. This can cause useEffect hooks to cancel fetch requests that were in flight. If models appear stuck on "Loading...", this is expected in development and will not occur in production builds.
File Upload Hangs
Symptoms
- Drag-and-drop file attachment shows a spinning circle indefinitely
- File upload never completes
- Backend process becomes unresponsive during upload
Diagnosis
Use the File Pipeline Debugger in Platform Admin Console > Upload Test to pinpoint which phase fails. The debugger runs the same upload + scan flow as chat and shows a timing breakdown with error classification. See the File Pipeline Troubleshooting guide for the full diagnostic workflow.
Causes and Fixes
Blocking I/O in async endpoint:
If the backend scan_file endpoint performs synchronous CPU-bound operations (image detection, text extraction, PII detection) on the main event loop, it can block all other requests. The fix is to run these operations in a thread pool using asyncio.to_thread().
Check the backend logs for:
- Long gaps between request receipt and response
- No error messages (the request just hangs)
File too large:
Check the MAX_FILE_UPLOAD_SIZE setting. Default is 50 MB. Large files (especially PDFs with many pages) take longer to process. Check /health/file-pipeline for current worker memory usage.
Unsupported file format:
Not all file types are supported for PII scanning. Supported formats include: PDF, DOCX, XLSX, PPTX, CSV, TXT, HTML, MD, ZIP, TAR, 7z, RAR, EML, MBOX, PST, DICOM, HL7, and common image formats.
Chat Stream Fails After File Upload
Symptoms
- File uploads and scans successfully (shows "Redacted", threat count)
- Sending a message with the attachment returns "AI service temporarily unavailable"
- Frontend shows "Retrying... attempt 2 of 2" then fails
- Backend logs show
Worker (pid:XX) was sent SIGKILL! Perhaps out of memory? - HTTP 502 on the chat stream endpoint
Causes
The chat stream endpoint processes file attachments (text extraction, PII detection, optional redaction) within the request handler. For large image-heavy files, this can cause the worker to exceed its memory limit and be killed by the OS.
Specific triggers include:
- RAG retrieval returning 0 chunks for vague queries, falling back to full PDF extraction
- Redundant PDF redaction when a redacted version already exists
- Multiple large files processed concurrently
Fixes
- Use the File Pipeline Debugger (Platform Admin > Upload Test) to reproduce the failure and identify the exact phase
- Check worker memory with
GET /health/file-pipeline-- ifpeak_rss_mbis high, workers are memory-stressed - See the File Pipeline Troubleshooting guide for detailed diagnosis and fixes
Authentication Issues
OAuth Login Fails
- Verify the OAuth provider (Google, GitHub, Microsoft, Apple) is configured with the correct client ID and secret
- Check that the redirect URI matches exactly (including trailing slash)
- Ensure the OAuth app is not restricted to specific email domains unless intended
JWT Token Expired
- Tokens expire after the configured
SESSION_TIMEOUT(default: 24 hours) - Users are automatically redirected to login
- If tokens expire too quickly, increase
SESSION_TIMEOUTin the environment
SSO Configuration
- SAML SSO requires a valid IdP metadata URL or uploaded metadata XML
- Use the SSO test mode (dry-run) to validate the configuration before enabling enforcement
- Check the SSO Configuration guide for provider-specific setup
Chat Issues
Responses Not Streaming
- Verify the browser supports Server-Sent Events (SSE)
- Check that no proxy or CDN is buffering the response
- Ensure the
Content-Type: text/event-streamheader is not being stripped
Model Not Available
- Check that the API key for the selected provider is valid in Settings → Provider Keys
- Use the Key Health page to verify key status
- Some models may be restricted by organization policies -- check with your admin
Thinking Indicator Stuck
- If the thinking indicator shows indefinitely, the LLM may be taking longer than expected
- Click "Stop" to abort the generation
- Try a different model or simplify the prompt
Admin Console Issues
Cannot Access Platform Admin
- Platform admin access requires the
is_platform_adminflag - This is set via environment variable (
PLATFORM_ADMIN_EMAIL) during initial setup - Existing admins can promote other users via Platform Admin Console → Users
AI Audit Tab Not Visible
- The AI Audit tab is only visible to platform admins and cloud admins
- Verify your role in the admin user directory
- If recently promoted, log out and log back in to refresh permissions
Connection Issues
"Connection Lost" Banner
- Check network connectivity
- Verify the backend is running and reachable
- If behind a load balancer, check health check configuration
- The connection status indicator in the sidebar shows real-time status
CORS Errors
- Ensure
CORS_ORIGINSincludes the frontend URL - In development, both
http://localhost:5173andhttp://localhost:5174(docs) should be allowed - Check browser console for the specific CORS error message
Getting More Help
- File pipeline issues: Use the File Pipeline Debugger in Platform Admin Console for end-to-end diagnosis
- Chat flow issues: Use the Chat Flow Debugger in Platform Admin Console > Chat Debug for per-request trace analysis
- Check the backend logs:
docker logs <backend-container> - Check the frontend console: Browser DevTools > Console
- Check system health:
curl http://localhost:8000/health/file-pipeline - Enable debug logging: Set
LOG_LEVEL=DEBUGin the backend environment - For AI detection issues specifically, enable AI Audit Logging at
summaryorfulllevel to inspect detection decisions