Common Issues

Overview

This guide covers common issues you may encounter when running the Nurse Handoff Helper application and their solutions.

Before troubleshooting, ensure you’ve completed the initial setup as described in the Getting Started guide and have all required environment variables configured.

API Configuration Issues

”API is not configured” Error

Problem: When trying to use AI analysis features, you receive an error that the API is not configured. Cause: Missing or invalid API keys in your .env file. Solution:

Verify your .env file exists in the project root directory
Check that your Anthropic API key is configured:

ANTHROPIC_API_KEY=your_anthropic_key_here

Ensure the API key is valid:
- Anthropic keys start with sk-ant-
Restart the backend server after modifying .env:

npm run server

Verify API Configuration

You can check which APIs are configured by calling the health endpoint:

curl http://localhost:3001/api/health

Expected response:

{
  "status": "ok",
  "availableProviders": {
    "claude": true,
    "supabase": true
  }
}

If a provider shows false, the API key is not configured correctly.

API Key Not Working

Problem: API key is configured but requests still fail. Possible causes and solutions:

Invalid or expired key:
- Regenerate the API key in the provider’s console
- Verify the key hasn’t been revoked
Rate limit exceeded:
- Check your usage in the provider’s dashboard
- Wait for rate limit reset
- Upgrade to higher tier if needed
Insufficient credits/quota:
- Add credits to your Anthropic account
- Check billing status in Anthropic Console
Network restrictions:
- Ensure your server can reach API endpoints
- Check firewall rules
- Verify no proxy configuration issues

Never commit API keys to version control. If you accidentally commit a key, revoke it immediately and generate a new one.

Server Issues

Server Not Starting

Problem: Backend server fails to start or crashes immediately. Common causes and solutions:

Port Already in Use

Symptom: Error message Error: listen EADDRINUSE: address already in use :::3001Cause: Another process is using port 3001.Solutions:

Find and kill the process:

# On Linux/Mac
lsof -i :3001
kill -9 <PID>

# On Windows
netstat -ano | findstr :3001
taskkill /PID <PID> /F

Change the port in .env:

PORT=3002

Then restart the server:

npm run server

Missing Dependencies

Symptom: Error about missing modules like Cannot find module 'express'Cause: Dependencies not installed.Solution:

npm install

If issues persist, try:

rm -rf node_modules package-lock.json
npm install

Supabase Connection Error

Symptom: Server starts but database operations fail.Cause: Invalid Supabase credentials.Solution:

Verify Supabase environment variables:

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_KEY=your_service_key

Check Supabase project status at app.supabase.com
Verify API keys haven’t been revoked
Ensure your IP isn’t blocked (check Supabase dashboard)

Frontend Not Connecting to Backend

Problem: Frontend loads but API requests fail. Symptoms:

Network errors in browser console
“Failed to fetch” errors
Timeout errors

Solutions:

Verify backend is running:

curl http://localhost:3001/api/health

Check CORS configuration (server/index.js:15):

app.use(cors()); // Should allow all origins in development

Verify API endpoint URL in frontend code:

// Should use http://localhost:3001 in development
const API_URL = 'http://localhost:3001';

Check browser console for specific error messages

Image Upload Issues

Images Not Analyzing

Problem: Image upload succeeds but analysis fails or returns no results. Solutions:

File Size Too Large

Cause: Image exceeds the 10MB limit (server/index.js:23).Solution:

Compress the image before uploading:
- Use image editing software
- Reduce resolution if very high
- Convert to JPEG format (usually smaller)
Increase server limit (if appropriate):

// server/index.js
const upload = multer({
  storage,
  limits: { fileSize: 20 * 1024 * 1024 }, // 20MB
});

Also update JSON limit:

app.use(express.json({ limit: "100mb" }));

Unsupported File Format

Cause: File format not supported by AI provider.Solution:Supported formats:

JPEG/JPG
PNG
GIF
WebP

Convert other formats (BMP, TIFF, etc.) to JPEG or PNG before uploading.

Image Quality Issues

Cause: Image is too blurry, dark, or low quality for AI to read text.Solution:

Ensure good lighting when taking photos
Hold camera steady to avoid blur
Get close enough to make text readable
Clean whiteboard before photographing
Use higher resolution camera if available
Avoid glare and reflections

”No image file provided” Error

Problem: Upload appears to work but server reports no file. Causes and solutions:

Form encoding issue: Ensure frontend sends multipart/form-data:

const formData = new FormData();
formData.append('image', file);

fetch('/api/analyze-image/claude', {
  method: 'POST',
  body: formData // Don't set Content-Type header
});

File input name mismatch: Server expects field name image (server/index.js:65)
File size limit in nginx/proxy: Check reverse proxy configuration if using one

Database Issues

Authentication Failures

Problem: Users cannot log in or get authentication errors.

Nurse Account Not Created

Cause: Nurse exists in database but has no Supabase Auth account.Solution:Create auth accounts for all nurses:

curl -X POST http://localhost:3001/api/nurses/create-accounts

This requires SUPABASE_SERVICE_KEY in your .env file.

Invalid Credentials

Cause: Wrong email or password.Solution:

Verify email address is correct
Check if account was created successfully
Reset password if needed using Supabase Auth UI
Check Supabase Auth logs for failed login attempts

Email Not Confirmed

Cause: Supabase requires email confirmation but nurse hasn’t confirmed.Solution:The /api/nurses/create-accounts endpoint auto-confirms emails (server/index.js:662).If using manual account creation:

email_confirm: true // Add this parameter

Patient Data Not Loading

Problem: Patient list is empty or specific patient won’t load. Solutions:

Verify database has data:
- Check Supabase dashboard
- Query patients table directly
- Ensure Row Level Security policies allow access
Check API response:

curl http://localhost:3001/api/patients

Review RLS policies: Supabase Row Level Security may be blocking access
Check for errors in server logs:

npm run server
# Look for database error messages

Handoff Notes Not Saving

Problem: Generated handoff notes don’t save to patient record. Debugging steps:

Check browser console for error messages
Verify API request succeeds:

curl -X POST http://localhost:3001/api/patients/MRN123/handoff \
  -H "Content-Type: application/json" \
  -d '{"handoffNotes": "Test notes"}'

Check server logs (server/index.js:469-554) for detailed error information
Verify patient exists with the given MRN
Check database permissions - ensure handoff_notes column is writable

Build and Deployment Issues

Build Fails

Problem: npm run build fails with errors.

TypeScript/ESLint Errors

Cause: Code has type errors or linting issues.Solution:

Review and fix errors shown in build output
Run linter to see all issues:

npm run lint

Fix issues or temporarily disable strict mode (not recommended for production)

Out of Memory

Symptom: JavaScript heap out of memory error during build.Solution:Increase Node.js memory limit:

export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

Or update package.json:

{
  "scripts": {
    "build": "NODE_OPTIONS=--max-old-space-size=4096 vite build"
  }
}

Missing Environment Variables

Cause: Frontend requires certain variables at build time.Solution:Ensure VITE_* variables are set during build:

VITE_SUPABASE_URL=xxx VITE_SUPABASE_ANON_KEY=xxx npm run build

Or use .env.production file.

Production Deployment Issues

Problem: App works locally but fails in production. Common issues:

Environment variables not set: Verify all required variables in production environment
CORS errors: Update CORS configuration for production domain:

app.use(cors({
  origin: process.env.FRONTEND_URL
}));

HTTPS required: Ensure SSL certificate is properly configured
Port issues: Production platform may assign different port:

const PORT = process.env.PORT || 3001;

Static files not served: If using monolithic deployment, ensure static file serving is configured

Performance Issues

Slow AI Responses

Problem: AI analysis takes a long time or times out. Causes and solutions:

Large image files: Compress images before uploading (under 5MB recommended)
Complex patient records: Very detailed records take longer to analyze
API provider latency: Check Anthropic Status
Network issues: Test connection to Anthropic API endpoints

Claude Sonnet 4 typically responds in 3-10 seconds. If consistently slower, investigate network or API issues.

High Server Memory Usage

Problem: Backend server uses excessive memory. Causes:

Image uploads in memory: Large images stored in memory during processing
Multiple concurrent requests: Many simultaneous AI requests
Memory leak: Check for unclosed connections or circular references

Solutions:

Reduce file size limit
Implement request queuing
Scale horizontally (multiple server instances)
Monitor memory usage and restart server if necessary

Getting Additional Help

Enabling Debug Logging

The server logs important information to console. View logs:

npm run server

Look for:

=== ... === sections showing detailed operation logs
Error messages with stack traces
Supabase query details
AI provider responses

Checking System Health

Verify system components:

# Check server health
curl http://localhost:3001/api/health

# Check Supabase connection
curl http://localhost:3001/api/nurses

# Check AI provider (Claude)
curl -X POST http://localhost:3001/api/analyze-image/claude \
  -F "image=@test-image.jpg"

Reporting Issues

When reporting issues, include:

Error message: Full error text from console or browser
Steps to reproduce: What actions trigger the issue
Environment: Development or production, OS, Node version
Configuration: Which AI providers are enabled
Logs: Relevant server logs (redact sensitive info)
Browser console: Any frontend errors

Common Error Messages Reference

Error Messages Quick Reference

Error Message	Cause	Solution
”API is not configured”	Missing API key	Add key to `.env` and restart server
”EADDRINUSE”	Port already in use	Change port or kill process
”Cannot find module”	Missing dependencies	Run `npm install`
”Failed to fetch”	Backend not running	Start backend with `npm run server`
”No image file provided”	Upload configuration issue	Check FormData and field name
”Patient not found”	Invalid MRN	Verify patient exists in database
”Failed to save handoff notes”	Database permission issue	Check RLS policies and column permissions
”Rate limit exceeded”	Too many API requests	Wait for reset or upgrade plan
”Insufficient credits”	No API credits remaining	Add credits to account
”Network error”	Connectivity issue	Check internet and firewall

Preventive Measures

Regular Maintenance

Update dependencies: Run npm update monthly
Monitor API usage: Check provider dashboards weekly
Review logs: Check for recurring errors
Test backups: Verify database backups work
Document issues: Keep a log of problems and solutions

Testing Checklist

Before deploying changes:

Need More Help?

If you’re still experiencing issues:

Review the Production Deployment guide
Check Security Best Practices
Consult your organization’s IT support
Review Supabase documentation for database issues
Check AI provider documentation for API issues

Deploy

Troubleshooting

Overview

API Configuration Issues

”API is not configured” Error

API Key Not Working

Server Issues

Server Not Starting

Frontend Not Connecting to Backend

Image Upload Issues

Images Not Analyzing

”No image file provided” Error

Database Issues

Authentication Failures

Patient Data Not Loading

Handoff Notes Not Saving

Build and Deployment Issues

Build Fails

Production Deployment Issues

Performance Issues

Slow AI Responses

High Server Memory Usage

Getting Additional Help

Enabling Debug Logging

Checking System Health

Reporting Issues

Common Error Messages Reference

Preventive Measures

Regular Maintenance

Testing Checklist

Need More Help?

Build docs developers (and LLMs) love

Deploy

Troubleshooting

​Overview

​API Configuration Issues

​”API is not configured” Error

​API Key Not Working

​Server Issues

​Server Not Starting

​Frontend Not Connecting to Backend

​Image Upload Issues

​Images Not Analyzing

​”No image file provided” Error

​Database Issues

​Authentication Failures

​Patient Data Not Loading

​Handoff Notes Not Saving

​Build and Deployment Issues

​Build Fails

​Production Deployment Issues

​Performance Issues

​Slow AI Responses

​High Server Memory Usage

​Getting Additional Help

​Enabling Debug Logging

​Checking System Health

​Reporting Issues

​Common Error Messages Reference

​Preventive Measures

​Regular Maintenance

​Testing Checklist

​Need More Help?

Build docs developers (and LLMs) love

Overview

API Configuration Issues

”API is not configured” Error

API Key Not Working

Server Issues

Server Not Starting

Frontend Not Connecting to Backend

Image Upload Issues

Images Not Analyzing

”No image file provided” Error

Database Issues

Authentication Failures

Patient Data Not Loading

Handoff Notes Not Saving

Build and Deployment Issues

Build Fails

Production Deployment Issues

Performance Issues

Slow AI Responses

High Server Memory Usage

Getting Additional Help

Enabling Debug Logging

Checking System Health

Reporting Issues

Common Error Messages Reference

Preventive Measures

Regular Maintenance

Testing Checklist

Need More Help?