Troubleshooting Guide

Even in the most robust systems, issues arise. This guide provides step-by-step instructions for diagnosing and resolving the most common operational and application-level issues encountered while hosting, deploying, or developing Trackr.

Before diving into specific issues, always ensure you have gathered the basic context:

• What version of Trackr are you running?
• Are you seeing errors in the browser console, the server logs, or the database logs?
• Did this issue start after a recent deployment or configuration change?

1. Authentication & Session Issues

Symptom: Users cannot log in, or they are inexplicably logged out immediately after logging in.

Potential Causes & Solutions:

• Missing NEXTAUTH_SECRET: NextAuth requires a strong, uniquely generated secret to encrypt JWTs. Fix: Ensure the NEXTAUTH_SECRET environment variable is set. You can generate one using openssl rand -base64 32.
• NEXTAUTH_URL Mismatch: If the application is hosted at https://trackr.company.com but NEXTAUTH_URL is set to http://localhost:3000, the callback URLs will fail. Fix: Set NEXTAUTH_URL to the exact public-facing base URL of your application.
• Secure Cookie Issues (HTTPS vs HTTP): In production, Trackr sets Secure cookies. If you are accessing the site via http:// (without SSL) or if your reverse proxy is not passing the correct X-Forwarded-Proto header, the browser will reject the session cookie. Fix: Ensure SSL is terminated correctly and your proxy sends proxy_set_header X-Forwarded-Proto $scheme;.
• Clock Skew: If your server's clock is out of sync, JWTs may be evaluated as expired the moment they are created. Fix: Ensure NTP (Network Time Protocol) is running and synchronized on your host machines.

2. Database Connection Failures

Symptom: The application crashes on startup with P1001: Can't reach database server or HTTP 500 errors across all routes mentioning Prisma.

Potential Causes & Solutions:

• Incorrect DATABASE_URL: Double-check the connection string syntax: postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public.
• Network/Firewall Rules: If the database is hosted on AWS RDS or a separate VPC, ensure the security groups allow inbound traffic on port 5432 from the compute instances.
• Connection Pool Exhaustion: P2024: Timed out fetching a new connection from the connection pool. This occurs during high traffic if the app creates too many connections. Fix: Implement PgBouncer. Update your DATABASE_URL in Trackr to point to the PgBouncer port (usually 6432) and append ?pgbouncer=true to the Prisma connection string.
• Pending Migrations: If the database connects but queries fail with "column does not exist", your schema is out of sync. Fix: Run npx prisma migrate deploy in your CI/CD pipeline or manually against the database.

3. Background Jobs & Webhooks Not Processing

Symptom: Job applications are created, but AI resume parsing hangs on "Processing...", and webhooks are not being dispatched.

Potential Causes & Solutions:

• Worker Service is Down: Trackr separates web traffic and background jobs. If you deployed using Docker, ensure the worker container is running.
• Redis Connection Issues: BullMQ (the queueing system) requires Redis. Check if the REDIS_URL environment variable is correct and the Redis server is accepting connections. You can test this using redis-cli -u <REDIS_URL> ping.
• Job Failures & Dead Letter Queue: Sometimes jobs fail due to external API errors (e.g., OpenAI API timeouts for resume parsing). Fix: Connect to Redis using a GUI like RedisInsight, look for the trackr:bullmq:failed sets. Inspect the stack trace. If the external API was temporarily down, you can manually retry the failed jobs.

4. AI & Resume Parsing Errors

Symptom: Uploading a PDF resume results in a "Failed to extract text" or "AI extraction failed" error on the frontend.

Potential Causes & Solutions:

• Invalid File Format / Corrupted PDF: The parser only supports standard PDFs and DOCX files. Ensure the uploaded file is valid and readable (not an image-only PDF without OCR).
• Missing API Keys: If you are using OpenAI for parsing, ensure OPENAI_API_KEY is set correctly. Check your OpenAI dashboard for billing limits or quota exhaustion (HTTP 429 Too Many Requests from OpenAI).
• File Size Limits: By default, Next.js API routes limit request bodies to 4MB. If the resume is larger, the upload will fail before processing begins. Fix: If you must accept larger files, adjust the bodyParser.sizeLimit config in the specific API route.

5. UI and Asset Loading Issues (404s)

Symptom: The site loads, but styles are broken, or images/icons return 404 Not Found.

Potential Causes & Solutions:

• Vercel / Next.js Build Cache: Sometimes stale build cache causes mismatching asset hashes. Fix: Trigger a clean build. In Vercel, use the "Redeploy with empty cache" option. Locally, delete the .next folder and run npm run build again.
• Storage Configuration (Avatars/Logos): If user avatars or company logos are missing, the S3 bucket configuration might be incorrect. Fix: Verify AWS_S3_BUCKET_NAME, AWS_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY. Ensure the IAM user has s3:GetObject and s3:PutObject permissions.

Logging & Monitoring Best Practices

When troubleshooting, having good visibility is key.

1. Centralized Logging: Do not rely on docker logs. Pipe stdout/stderr to a centralized logging system like Datadog, ELK stack (Elasticsearch, Logstash, Kibana), or AWS CloudWatch.
2. Application Performance Monitoring (APM): Use Sentry or DataDog APM. Sentry will automatically capture unhandled exceptions, including React rendering errors and backend Prisma panics, grouping them and providing exact stack traces.
3. Database Insights: Monitor PostgreSQL pg_stat_statements to identify slow queries that might be causing frontend timeouts.

If you have exhausted this guide and are still experiencing issues, Enterprise customers can open a high-priority ticket via the Support Portal. Open-source users are encouraged to search closed issues in our GitHub repository or open a new Discussion.