.. _troubleshooting:

===============
Troubleshooting
===============

This guide helps you resolve common issues with the tiger Rating Engine, from calculation errors to system configuration problems.

.. contents:: Quick Navigation
   :local:
   :depth: 2

Common Issues
=============

Calculation Errors
------------------

**Issue: "No rates found for effective date"**

.. figure:: _static/screenshots/no_rates_error.png
   :alt: No Rates Found Error
   :align: center
   :width: 80%

   *Screenshot Placeholder: Error message showing "No rates found for effective date 2025-03-01" with details*

**Symptoms:**
- Calculation fails immediately
- Error mentions missing rates or tables
- Specific effective date referenced

**Solutions:**

1. Verify effective date is valid:

   .. code-block:: text

      Check: Product effective date <= Your date <= Product end date
      Example: 2025-01-01 <= 2025-03-01 <= (no end date) ✓

2. Check table values exist for date:

   - Navigate to **Admin** → **Rating Table Values**
   - Filter by product and effective date
   - Ensure values exist for all dimension combinations

3. Verify product is active:

   - Go to **Admin** → **Products**
   - Check "Is Active" checkbox is selected

**Issue: "Required field missing"**

.. figure:: _static/screenshots/required_field_error.png
   :alt: Required Field Error
   :align: center
   :width: 80%

   *Screenshot Placeholder: Form with red highlighted fields showing "Territory is required" error message*

**Solutions:**

.. table:: Required Field Solutions
   :widths: 30 70

   +------------------+------------------------------------------------+
   | Field Type       | Solution                                       |
   +==================+================================================+
   | Territory        | Select from dropdown or enter valid code      |
   +------------------+------------------------------------------------+
   | Building Value   | Enter numeric value within min/max range      |
   +------------------+------------------------------------------------+
   | Effective Date   | Select date after product start date          |
   +------------------+------------------------------------------------+
   | Coverage Limits  | Enter values meeting minimum requirements     |
   +------------------+------------------------------------------------+

**Issue: "Formula execution timeout"**

**Symptoms:**
- Calculation takes too long
- Timeout error after 30 seconds
- Complex formulas involved

**Solutions:**

1. Simplify formulas:
   - Break complex calculations into steps
   - Avoid nested loops in Python expressions
   - Pre-calculate values in tables

2. Optimize table lookups:
   - Add indexes to frequently accessed dimensions
   - Reduce table size by removing unused values

3. Contact support for formula review

Authentication Issues
---------------------

**Issue: "Invalid credentials"**

.. figure:: _static/screenshots/auth_error.png
   :alt: Authentication Error
   :align: center
   :width: 60%

   *Screenshot Placeholder: Login screen with "Invalid username or password" error message*

**Solutions:**

1. **Password Reset:**

   - Click "Forgot Password?" link
   - Enter email address
   - Check email for reset link
   - Create new password

2. **Account Locked:**

   - After 5 failed attempts, account locks for 15 minutes
   - Wait or contact administrator

3. **API Token Issues:**

   .. code-block:: bash

      # Check token expiration
      curl -X GET https://api.tigerrating.com/v1/auth/verify \
        -H "Authorization: Bearer {token}"

      # Refresh if expired
      curl -X POST https://api.tigerrating.com/v1/auth/refresh \
        -d '{"refresh_token": "your_refresh_token"}'

Data Entry Problems
-------------------

**Issue: "Value out of acceptable range"**

.. figure:: _static/screenshots/value_range_error.png
   :alt: Value Range Error
   :align: center
   :width: 80%

   *Screenshot Placeholder: Input field showing "Building value must be between $50,000 and $10,000,000"*

**Common Range Issues:**

.. table:: Field Ranges
   :widths: 25 25 25 25

   +-----------------+----------+------------+-------------+
   | Field           | Minimum  | Maximum    | Common Issue|
   +=================+==========+============+=============+
   | Building Value  | $50,000  | $10,000,000| Too low     |
   +-----------------+----------+------------+-------------+
   | Employees       | 1        | 10,000     | Zero entered|
   +-----------------+----------+------------+-------------+
   | Revenue         | $100,000 | $100,000,000| Format error|
   +-----------------+----------+------------+-------------+
   | Deductible      | $500     | $50,000    | Invalid option|
   +-----------------+----------+------------+-------------+

**Issue: "Invalid territory code"**

**Solutions:**

1. Check valid territory codes:
   - View product configuration
   - See allowed values list
   - Common codes: 001, 002, 003

2. Territory lookup:
   - Use ZIP code to find territory
   - Check territory map in documentation

Performance Issues
==================

Slow Calculations
-----------------

**Issue: Calculations taking too long**

.. figure:: _static/screenshots/performance_monitor.png
   :alt: Performance Monitor
   :align: center
   :width: 100%

   *Screenshot Placeholder: Performance dashboard showing calculation time graph with spike*

**Diagnosis Steps:**

1. **Check calculation complexity:**

   .. code-block:: text

      Review in Rating History:
      - Execution time (should be <5 seconds)
      - Number of formulas executed
      - Table lookup count

2. **Identify bottlenecks:**

   - Complex Python expressions
   - Large table lookups
   - Multiple nested calculations

**Solutions:**

- Optimize formulas (contact support)
- Use cached results when available
- Break into smaller calculations

Page Loading Issues
-------------------

**Issue: Dashboard or pages load slowly**

**Solutions:**

1. **Clear browser cache:**
   - Chrome: Ctrl+Shift+Delete
   - Firefox: Ctrl+Shift+Delete
   - Safari: Cmd+Option+E

2. **Check network connection:**
   - Run speed test
   - Try different network
   - Check VPN if applicable

3. **Browser compatibility:**
   - Use Chrome, Firefox, or Safari (latest versions)
   - Disable browser extensions temporarily

Configuration Problems
======================

Product Setup Errors
--------------------

**Issue: "Product configuration incomplete"**

.. figure:: _static/screenshots/product_config_error.png
   :alt: Product Configuration Error
   :align: center
   :width: 100%

   *Screenshot Placeholder: Product validation showing missing factors, tables, and formulas with red X marks*

**Configuration Checklist:**

.. code-block:: text

   Product Setup Requirements:
   ☐ Product basic information
   ☐ At least one rating factor
   ☐ Required rating tables
   ☐ Calculation formulas
   ☐ Effective date set
   ☐ Product activated

**Issue: "Circular formula dependency"**

**Symptoms:**
- Formula A depends on B, B depends on A
- Calculation fails with dependency error

**Solution:**
1. Review formula execution order
2. Ensure linear dependency chain
3. Remove circular references

Table Configuration
-------------------

**Issue: "Table dimension mismatch"**

.. figure:: _static/screenshots/table_dimension_error.png
   :alt: Table Dimension Error
   :align: center
   :width: 100%

   *Screenshot Placeholder: Table configuration showing dimension error with expected vs actual dimensions*

**Solutions:**

1. Verify dimensions match factors:
   - Each dimension must map to a rating factor
   - Factor data types must be compatible

2. Check table values:
   - All dimension combinations should have values
   - Use "Generate Permutations" tool

API Integration Issues
======================

Connection Problems
-------------------

**Issue: "Unable to connect to API"**

**Diagnostic Steps:**

.. code-block:: bash

   # Test API connectivity
   curl -I https://api.tigerrating.com/v1/health

   # Check DNS resolution
   nslookup api.tigerrating.com

   # Verify SSL certificate
   openssl s_client -connect api.tigerrating.com:443

**Common Causes:**

.. table:: API Connection Issues
   :widths: 30 70

   +-------------------+------------------------------------------------+
   | Issue             | Resolution                                     |
   +===================+================================================+
   | Firewall blocking | Whitelist api.tigerrating.com                |
   +-------------------+------------------------------------------------+
   | SSL/TLS error     | Update certificates, use TLS 1.2+            |
   +-------------------+------------------------------------------------+
   | DNS issues        | Use Google DNS (8.8.8.8)                     |
   +-------------------+------------------------------------------------+
   | Proxy problems    | Configure proxy settings                      |
   +-------------------+------------------------------------------------+

Rate Limiting
-------------

**Issue: "Rate limit exceeded"**

.. figure:: _static/screenshots/rate_limit_error.png
   :alt: Rate Limit Error
   :align: center
   :width: 80%

   *Screenshot Placeholder: API response showing 429 error with rate limit headers*

**Solutions:**

1. **Check current limits:**

   .. code-block:: text

      Response Headers:
      X-RateLimit-Limit: 1000
      X-RateLimit-Remaining: 0
      X-RateLimit-Reset: 1612137600

2. **Implement backoff:**

   .. code-block:: python

      import time

      def api_call_with_retry(func, *args, **kwargs):
          max_retries = 3
          for attempt in range(max_retries):
              try:
                  return func(*args, **kwargs)
              except RateLimitError as e:
                  wait_time = e.reset_time - time.time()
                  time.sleep(wait_time)

3. **Upgrade plan if needed**

Data Issues
===========

Import/Export Problems
----------------------

**Issue: "CSV import failed"**

.. figure:: _static/screenshots/csv_import_error.png
   :alt: CSV Import Error
   :align: center
   :width: 100%

   *Screenshot Placeholder: Import dialog showing error "Row 5: Invalid date format" with preview*

**Common CSV Issues:**

.. code-block:: text

   Format Requirements:
   - UTF-8 encoding
   - Comma-separated (not semicolon)
   - Headers must match exactly
   - Dates in YYYY-MM-DD format
   - Numbers without currency symbols

**Solution Template:**

.. code-block:: text

   product_code,effective_date,territory,building_value,deductible
   BOP,2025-02-01,001,500000,1000
   BOP,2025-02-01,002,750000,2500

Data Validation
---------------

**Issue: "Data consistency error"**

**Check for:**

1. Duplicate entries
2. Orphaned records
3. Invalid references
4. Data type mismatches

**Cleanup Script:**

.. code-block:: sql

   -- Find duplicate table values
   SELECT product_id, dimension_values, effective_date, COUNT(*)
   FROM rating_table_values
   GROUP BY product_id, dimension_values, effective_date
   HAVING COUNT(*) > 1;

System Administration
=====================

User Management
---------------

**Issue: "Cannot create new user"**

.. figure:: _static/screenshots/user_creation_error.png
   :alt: User Creation Error
   :align: center
   :width: 80%

   *Screenshot Placeholder: User creation form with error "Email already exists"*

**Solutions:**

1. Check existing users
2. Verify email format
3. Ensure unique username
4. Assign proper role

Permission Issues
-----------------

**Issue: "Access denied to configuration"**

**Role Requirements:**

.. table:: Permission Matrix
   :widths: 25 25 25 25

   +------------------+--------+------------+-------+
   | Action           | Viewer | Underwriter| Admin |
   +==================+========+============+=======+
   | View products    | ✓      | ✓          | ✓     |
   +------------------+--------+------------+-------+
   | Calculate premium| ✗      | ✓          | ✓     |
   +------------------+--------+------------+-------+
   | Configure products| ✗     | ✗          | ✓     |
   +------------------+--------+------------+-------+
   | Manage users     | ✗      | ✗          | ✓     |
   +------------------+--------+------------+-------+

Emergency Procedures
====================

System Down
-----------

**If entire system is unavailable:**

1. **Check status page:** https://status.tigerrating.com
2. **Verify network connectivity**
3. **Contact support immediately**
4. **Use backup procedures if available**

Data Recovery
-------------

**If data appears lost:**

1. **Don't panic** - system has automatic backups
2. **Note exact time of issue**
3. **Document what was lost**
4. **Contact support with details**

Rollback Procedure
------------------

**If bad configuration deployed:**

.. code-block:: text

   Emergency Rollback Steps:
   1. Access Admin panel
   2. Go to Product Versions
   3. Select previous version
   4. Click "Restore Version"
   5. Confirm effective immediately
   6. Test with sample calculation

Getting Help
============

Support Channels
----------------

.. figure:: _static/screenshots/support_channels.png
   :alt: Support Channels
   :align: center
   :width: 100%

   *Screenshot Placeholder: Support page showing chat widget, email form, and phone number*

**Priority Support:**

.. table:: Support Response Times
   :widths: 20 20 20 20 20

   +-----------+---------+---------+---------+----------+
   | Channel   | Critical| High    | Medium  | Low      |
   +===========+=========+=========+=========+==========+
   | Phone     | < 15 min| < 1 hr  | < 4 hrs | Next day |
   +-----------+---------+---------+---------+----------+
   | Email     | < 30 min| < 2 hrs | < 8 hrs | 2 days   |
   +-----------+---------+---------+---------+----------+
   | Chat      | < 5 min | < 30 min| < 2 hrs | < 8 hrs  |
   +-----------+---------+---------+---------+----------+

Information to Provide
----------------------

When contacting support:

.. code-block:: text

   Required Information:
   ☐ Your username/account
   ☐ Time of issue (with timezone)
   ☐ Product and version affected
   ☐ Error message (exact text)
   ☐ Steps to reproduce
   ☐ Screenshots if applicable
   ☐ Run ID for calculations

   Optional but Helpful:
   ☐ Browser and version
   ☐ Network environment
   ☐ Recent changes made
   ☐ Workarounds tried

Self-Service Resources
----------------------

Before contacting support:

1. **Knowledge Base:** https://help.tigerrating.com
2. **Video Tutorials:** https://learn.tigerrating.com
3. **Community Forum:** https://forum.tigerrating.com
4. **API Documentation:** https://api.tigerrating.com/docs
5. **Status Page:** https://status.tigerrating.com

Diagnostic Tools
================

Built-in Diagnostics
--------------------

.. figure:: _static/screenshots/diagnostic_panel.png
   :alt: Diagnostic Panel
   :align: center
   :width: 100%

   *Screenshot Placeholder: Diagnostic panel showing system health checks with green checkmarks and red X's*

Access diagnostics:

1. Navigate to **Settings** → **Diagnostics**
2. Run health checks:
   - Database connectivity
   - API availability
   - Cache status
   - Formula validation

Log Analysis
------------

View system logs:

.. code-block:: text

   Log Locations:
   /admin/logs/          - Admin activity
   /api/logs/           - API requests
   /rating/logs/        - Calculation logs
   /system/logs/        - System events

Browser Console
---------------

Check for client-side errors:

1. Open Developer Tools (F12)
2. Go to Console tab
3. Look for red error messages
4. Copy errors for support

Prevention Tips
===============

Best Practices
--------------

**Avoid common issues:**

1. **Regular Testing:**
   - Test calculations after changes
   - Verify formulas with edge cases
   - Check all products monthly

2. **Documentation:**
   - Document custom configurations
   - Keep change log
   - Note workarounds used

3. **Training:**
   - Attend quarterly training
   - Review documentation updates
   - Share knowledge with team

Regular Maintenance
-------------------

.. code-block:: text

   Monthly Checklist:
   ☐ Review error logs
   ☐ Check calculation performance
   ☐ Verify table data integrity
   ☐ Test sample calculations
   ☐ Update documentation
   ☐ Review user feedback

Monitoring Setup
----------------

Set up alerts for:

- Failed calculations > 5%
- Response time > 5 seconds
- API errors > 1%
- Database connection issues
- Storage > 80% full

Quick Reference
===============

Error Code Reference
--------------------

.. table:: Common Error Codes
   :widths: 20 40 40

   +--------+--------------------------------+---------------------------+
   | Code   | Meaning                        | Quick Fix                 |
   +========+================================+===========================+
   | E1001  | Missing required field         | Fill all required fields  |
   +--------+--------------------------------+---------------------------+
   | E1002  | Invalid data format            | Check format requirements |
   +--------+--------------------------------+---------------------------+
   | E2001  | No rates found                 | Verify effective date     |
   +--------+--------------------------------+---------------------------+
   | E2002  | Formula execution failed       | Review formula syntax     |
   +--------+--------------------------------+---------------------------+
   | E3001  | Authentication failed          | Check credentials         |
   +--------+--------------------------------+---------------------------+
   | E3002  | Insufficient permissions       | Contact administrator     |
   +--------+--------------------------------+---------------------------+
   | E4001  | API rate limit exceeded        | Wait or upgrade plan      |
   +--------+--------------------------------+---------------------------+
   | E5001  | Database connection error      | Contact support           |
   +--------+--------------------------------+---------------------------+

Keyboard Shortcuts
------------------

.. table:: Troubleshooting Shortcuts
   :widths: 30 70

   +------------------+--------------------------------+
   | Shortcut         | Action                         |
   +==================+================================+
   | Ctrl+Shift+D     | Open diagnostics panel         |
   +------------------+--------------------------------+
   | Ctrl+Shift+L     | View recent logs               |
   +------------------+--------------------------------+
   | Ctrl+Shift+H     | Show help for current page     |
   +------------------+--------------------------------+
   | F12              | Open browser developer tools   |
   +------------------+--------------------------------+

.. tip::
   Keep this troubleshooting guide bookmarked for quick reference when issues arise.

.. warning::
   Never share screenshots containing sensitive data or API credentials when seeking help.