Skip to main content

Troubleshooting Guide

Step-by-step solutions for common issues

Login Issues​

Cannot Log In​

Symptom: Login fails with "Invalid credentials"

Causes & Solutions:

  1. Wrong username/password

    • ✅ Check spelling (case-sensitive)
    • ✅ Try email if you have one
    • ✅ Contact admin for password reset

  2. Account locked

    • ✅ Wait 15 minutes (5 failed attempts = lockout)
    • ✅ Or contact admin to unlock

  3. Account deactivated

    • ✅ Contact admin
    • ✅ May need reactivation if returning employee

  4. Browser issues

    • ✅ Clear cache and cookies
    • ✅ Try different browser
    • ✅ Enable cookies/JavaScript

Session Expired​

Symptom: "Session expired, please log in again"

Cause: 30 minutes of inactivity (security feature)

Solution:

  • ✅ Log back in
  • ✅ Drafts auto-saved, work not lost
  • ✅ Use "Remember Me" for 7-day sessions

Patient Management Issues​

Cannot Find Patient​

Symptom: Patient not in search results

Solutions:

  1. Check spelling

    • ✅ Try last name only
    • ✅ Try DOB instead

  2. Check filters

    • ✅ "Include Inactive" may be off
    • ✅ Provider filter may be limiting results

  3. Verify patient exists

    • ✅ May be in different clinic (if multi-location)
    • ✅ Admin can check if deleted

Duplicate Patients​

Symptom: Same patient appears twice

Solution:

  • ✅ Contact admin to merge records
  • ✅ Choose which to keep
  • ✅ Data transferred from other record

Insurance Not Verifying​

Symptom: Eligibility check fails or shows inactive

Solutions:

  1. Verify member ID

    • ✅ Check with patient insurance card
    • ✅ Common error: O vs. 0, I vs. 1

  2. Try manual entry

    • ✅ Skip auto-verify
    • ✅ Enter information manually

  3. Wait and retry

    • ✅ Payer system may be down
    • ✅ Try again in 1 hour

  4. Confirm with payer

    • ✅ Call insurance company directly
    • ✅ Verify coverage by phone
    • ✅ Document call in patient notes

Documentation Issues​

Speech-to-Text Not Working​

Symptom: Microphone button not responding or "Access denied"

Solutions:

  1. Grant microphone permission

    • ✅ Browser prompts for permission
    • ✅ Or: Browser settings → Privacy → Microphone → Allow

  2. Check microphone

    • ✅ Not in use by another app
    • ✅ Correct microphone selected in browser
    • ✅ Test in system settings

  3. Browser compatibility

    • ✅ Use Chrome, Firefox, or Edge
    • ✅ Safari may have issues
    • ✅ Update to latest version

  4. Connection issues

    • ✅ Stable internet required
    • ✅ Check network connection
    • ✅ Try again

Fallback: Type notes manually if transcription unavailable

Lost Unsaved Work​

Symptom: Browser crashed, work not saved

Solution:

  • ✅ Reopen same patient/session
  • ✅ Click "Recover Draft" if prompted
  • ✅ Auto-save stores drafts every 30 seconds
  • ✅ If not recovered: check browser local storage manually or re-document

AI Suggestions Seem Wrong​

Symptom: AI suggests incorrect CPT code

Solution:

  • ✅ Override with correct code (system learns)
  • ✅ Check if duration was recorded correctly
  • ✅ Verify complexity factors documented
  • ✅ Report pattern of errors to admin

Scheduling Issues​

Double-Booked Appointment​

Symptom: Conflict warning when scheduling

Solutions:

  1. Check if intentional

    • ✅ Group therapy can overlap with individual slots
    • ✅ Override warning if intentional

  2. Find different time

    • ✅ Use availability view
    • ✅ Check other providers

  3. Remove conflicting appointment

    • ✅ Cancel or reschedule existing appointment first

CRD Check Not Working​

Symptom: No prior auth notice when scheduling

Solutions:

  1. Verify payer configured

    • ✅ Admin: Check if payer FHIR endpoint entered
    • ✅ May need manual prior auth check

  2. Payer system down

    • ✅ Try again later
    • ✅ Check payer website status
    • ✅ Call payer if urgent

  3. Connection issue

    • ✅ Check internet
    • ✅ Refresh page

Billing & Claims Issues​

Claim Submission Failed​

Symptom: Error message on submit

Common causes:

  1. Missing required fields

    • ✅ Review error message
    • ✅ Complete all required fields
    • ✅ Common: NPI, Tax ID, Member ID

  2. Invalid insurance information

    • ✅ Verify member ID with patient
    • ✅ Check if insurance active
    • ✅ Update patient record

  3. Prior authorization missing

    • ✅ Obtain authorization first
    • ✅ Or submit as no-auth if allowed
    • ✅ Expect denial if not obtained

  4. Payer system down

    • ✅ Try again in 1 hour
    • ✅ Check payer website
    • ✅ Save as draft to submit later

Claim Denied​

Symptom: Claim status shows "Denied"

Solutions by reason:

1. Prior authorization missing

  • ✅ Obtain retroactive auth if allowed (rare)
  • ✅ Appeal with clinical justification
  • ✅ Learn lesson: check CRD before scheduling

2. Medical necessity not established

  • ✅ Submit additional clinical notes
  • ✅ Include assessment scores
  • ✅ Document functional impairment
  • ✅ Appeal with stronger evidence

3. Non-covered service

  • ✅ Verify in payer policy manual
  • ✅ Appeal if policy actually covers it
  • ✅ If truly non-covered: bill patient

4. Incorrect coding

  • ✅ Review documentation
  • ✅ Correct code if wrong
  • ✅ Resubmit corrected claim
  • ✅ If code was correct: appeal with justification

5. Timely filing

  • ✅ Appeal if special circumstances
  • ✅ If truly late: bill patient (if allowed by contract)
  • ✅ Learn lesson: submit within 30 days

6. Patient not eligible

  • ✅ Verify insurance information
  • ✅ May have wrong policy period
  • ✅ Update and resubmit
  • ✅ If patient lied about coverage: collection issue

Authorization Expired​

Symptom: Denial for "authorization expired"

Prevention:

  • ✅ Use authorization tracking
  • ✅ Pay attention to yellow alerts (low sessions)
  • ✅ Renew 2-3 weeks before expiration

If it happened:

  • ✅ Obtain new authorization
  • ✅ Resubmit with new auth number
  • ✅ May be denied if service already provided

AI Feature Issues​

AI Codes Seem Conservative​

Symptom: AI always suggests lower-value codes than appropriate

Causes:

  • Model trained to avoid over-coding risk
  • May not detect complexity factors in documentation

Solutions:

  • ✅ Document complexity clearly
  • ✅ Use structured assessments (PHQ-9, GAD-7)
  • ✅ Override when appropriate
  • ✅ System learns from overrides
  • ✅ Admin: Review AI performance metrics

Denial Predictions Not Accurate​

Symptom: Flagged claims get paid, or unflagged claims get denied

Causes:

  • Model needs more training data
  • Payer policies changed
  • Unique situation not in training data

Solutions:

  • ✅ Continue submitting (AI learns from outcomes)
  • ✅ Admin: Review model performance
  • ✅ Admin: May need model retraining
  • ✅ Use as advisory only, not gospel

Appeal Letters Need Heavy Editing​

Symptom: AI draft doesn't match your style or needs major changes

Causes:

  • AI generates generic professional language
  • May not capture all clinical nuance

Solutions:

  • ✅ Edit draft heavily (that is expected)
  • ✅ Save edited version as template
  • ✅ Provide feedback to improve future drafts

Technical Issues​

Page Won't Load​

Solutions:

  1. Refresh page (Ctrl+R or Cmd+R)
  2. Clear browser cache (Ctrl+Shift+Delete)
  3. Try different browser
  4. Check internet connection
  5. Disable browser extensions (ad blockers can interfere)

Data Not Saving​

Symptom: Click Save but changes don't persist

Solutions:

  1. Check for error message (may be validation error)
  2. Try again (temporary connection issue)
  3. Refresh and re-enter (last resort)
  4. Contact support if persistent

Reports Not Generating​

Symptom: Report button does nothing or times out

Solutions:

  1. Reduce date range (large reports take time)
  2. Simplify filters (too many conditions slow query)
  3. Try during off-hours (less load on system)
  4. Export smaller chunks (month by month vs. full year)

Symptom: Forms don't print correctly

Solutions:

  1. Use print preview first
  2. Select correct paper size (US Letter)
  3. Check orientation (portrait vs. landscape)
  4. Adjust margins if content cut off
  5. Export to PDF if printing fails

Browser Issues​

Fully supported:

  • ✅ Chrome 90+
  • ✅ Firefox 88+
  • ✅ Edge 90+

Limited support:

  • ⚠️ Safari 14+ (some features may not work)

Not supported:

  • ❌ Internet Explorer (any version)
  • ❌ Older browser versions

Clearing Cache​

Chrome:

  1. Ctrl+Shift+Delete (Cmd+Shift+Delete on Mac)
  2. Select "Cached images and files"
  3. Clear data

Firefox:

  1. Ctrl+Shift+Delete
  2. Select "Cache"
  3. Clear now

Edge:

  1. Ctrl+Shift+Delete
  2. Select "Cached data and files"
  3. Clear

Cookies Required​

Turtle RCM requires cookies for:

  • Authentication (storing login token)
  • Session management
  • User preferences

Enable cookies:

  1. Browser settings → Privacy
  2. Allow cookies for Turtle RCM domain
  3. Or allow all cookies

Error Messages Explained​

"Invalid credentials"​

  • Wrong username or password
  • Try again carefully
  • Contact admin after 5 attempts (lockout)

"Session expired"​

  • 30 minutes of inactivity
  • Log back in
  • Work auto-saved

"Unauthorized"​

  • Your role doesn't have permission
  • Contact admin if you should have access
  • May need role change

"Validation error"​

  • Form field has invalid data
  • Check fields with red outline
  • Follow format hints (e.g., phone: XXX-XXX-XXXX)

"Network error"​

  • Internet connection issue
  • Check WiFi/ethernet
  • Retry in a minute

"Server error"​

  • Backend issue
  • Try again in 5 minutes
  • Contact support if persistent

Performance Tips​

For Faster Loading​

✅ DO:

  • Use modern browser (latest version)
  • Close unused tabs
  • Clear cache regularly
  • Use wired connection (not WiFi) if possible
  • Close other bandwidth-heavy apps

❌ DON'T:

  • Run too many apps simultaneously
  • Use old computer (upgrade if < 4GB RAM)
  • Keep 50+ tabs open
  • Use public WiFi (also security risk)

For Smoother Experience​

✅ DO:

  • Save work frequently (Ctrl+S)
  • Complete one task before starting another
  • Log out when finished

❌ DON'T:

  • Keep multiple Turtle RCM tabs open
  • Leave logged in overnight
  • Work offline (won't save)

Getting Additional Help​

Before Contacting Support​

Try these first:

  1. Search this troubleshooting guide
  2. Check FAQ
  3. Ask clinic administrator
  4. Refresh page
  5. Clear cache
  6. Try different browser
💡 Need Help?

For questions, support, or feedback:
💬 Join our Discord community (primary forum): discord.gg/SwE7zq8fbF
🐙 GitHub: @ab1nash
💡 Submit feedback through the platform's feedback button

Known Issues & Workarounds​

Issue: Safari and Speech-to-Text​

Status: Known limitation

Problem: Safari has limited Web Speech API support

Workaround: Use Chrome, Firefox, or Edge for speech-to-text

Issue: PDF Export Formatting​

Status: In progress

Problem: PDF exports may have formatting issues

Workaround: Use print to PDF from browser (Ctrl+P → Save as PDF)

Issue: Mobile Documentation​

Status: Works but suboptimal

Problem: Small screen makes documentation difficult

Workaround: Use desktop/laptop for full documentation. Mobile OK for quick notes.

Error Recovery​

If System Crashes​

You lose minimal work:

  • Forms auto-save every 30 seconds
  • Recover draft when you log back in
  • Can reconstruct from browser local storage if needed

If Data Looks Wrong​

Possible causes:

  • Cached old data
  • Display issue
  • Actual data corruption (rare)

Steps:

  1. Refresh page
  2. Clear cache
  3. Log out and back in
  4. If still wrong: contact support immediately
  5. Don't modify data if you think it's corrupt

FAQ​

Q: Why is the system slow?

  • Check internet speed, close other apps, try off-peak hours, contact support if persistent.

Q: Can I recover deleted data?

  • Depends. Deactivated users/patients can be reactivated. Deleted records may be in backup (contact support within 30 days).

Q: What if I entered wrong information?

  • Edit the record. If already submitted claim: void and resubmit. If signed note: add addendum.

Q: System says I need to update my browser

  • You are using outdated browser. Update to latest version for security and compatibility.
Last updated: November 2025