Troubleshooting Guide¶

This guide provides solutions for common issues you may encounter while using CalcBridge. If your issue is not covered here, please contact support@calcbridge.io.

Upload Issues¶

Upload Fails with "File Too Large"¶

Symptoms: - Error message: "File exceeds maximum size limit" - Upload progress stops at 0%

Solutions:

1. Check file size - Maximum default size is 100 MB
2. Remove unnecessary data:
3. Delete unused sheets
4. Remove historical data not needed for calculations
5. Clear formatting that increases file size
6. Split the workbook:
7. Separate data into multiple files
8. Upload each file separately
9. Request limit increase: Contact support for enterprise limits

Upload Fails with "Invalid File Format"¶

Symptoms: - Error message: "Unsupported file format" - File appears to be Excel but won't upload

Solutions:

1. Verify file extension - Must be .xlsx, .xls, or .xlsm
2. Check for file corruption:
3. Open the file in Excel
4. Save as a new file
5. Try uploading the new file
6. Convert file format:
7. If using .xlsb, save as .xlsx
8. If using .csv, import into Excel first
9. Remove password protection:
10. CalcBridge cannot open encrypted files
11. Remove password in Excel before upload

Upload Fails with "Parsing Error"¶

Symptoms: - Error message: "Failed to parse workbook" - Upload completes but processing fails

Solutions:

1. Fix formula errors in Excel first:
2. Look for #REF! errors (broken references)
3. Look for #NAME? errors (unknown functions)
4. Fix or remove problem formulas
5. Check for unsupported features:
6. External links (remove or break)
7. Data connections (remove)
8. Pivot tables (convert to values)
9. Simplify the workbook:
10. Remove charts and images
11. Remove conditional formatting
12. Remove data validation

Upload Stuck at Processing¶

Symptoms: - Upload reaches 100% but processing never completes - Status shows "Processing" indefinitely

Solutions:

1. Wait longer - Large files may take 5-10 minutes
2. Check workbook complexity:
3. Many cross-sheet references slow parsing
4. Reduce dependencies if possible
5. Try a smaller test file:
6. Upload a single sheet to test
7. Gradually add complexity
8. Clear browser cache and retry
9. Contact support if issue persists over 30 minutes

Calculation Errors¶

Formula Returns #VALUE! Error¶

Cause: Invalid input type for a function

Common scenarios:

Example fix:

# Before (error)
=A1+B1  # where B1 contains "N/A"

# After (fixed)
=A1+IF(ISNUMBER(B1), B1, 0)

Formula Returns #REF! Error¶

Cause: Invalid cell reference

Common scenarios:

Example fix:

# Before (error)
='Old Sheet Name'!A1

# After (fixed)
='New Sheet Name'!A1

Formula Returns #NAME? Error¶

Cause: Unknown function name or undefined name

Solutions:

1. Check function spelling - Functions are case-insensitive but must be spelled correctly
2. Verify function is supported - See Functions Reference
3. Check named ranges - Named ranges from Excel may not transfer
4. Remove custom functions - VBA/user-defined functions are not supported

Formula Returns #DIV/0! Error¶

Cause: Division by zero

Solution: Add error handling

# Before (error)
=A1/B1

# After (fixed)
=IF(B1=0, 0, A1/B1)
# or
=IFERROR(A1/B1, 0)

Formula Returns #N/A Error¶

Cause: Lookup value not found

Solution: Add default value

# Before (error)
=VLOOKUP(A1, B:C, 2, FALSE)

# After (fixed)
=IFERROR(VLOOKUP(A1, B:C, 2, FALSE), "Not Found")
# or
=XLOOKUP(A1, B:B, C:C, "Not Found")

Circular Reference Detected¶

Cause: Formula references itself directly or indirectly

Symptoms: - Error message: "Circular reference detected" - Calculation does not complete

Solutions:

1. Identify the cycle:
2. Check the error message for cell addresses
3. Trace precedents and dependents
4. Break the cycle:
5. Restructure formulas to avoid self-reference
6. Use intermediate calculation cells
7. Note: CalcBridge does not support iterative calculation like Excel

Calculation Times Out¶

Cause: Calculation exceeds time limit

Solutions:

1. Reduce complexity:
2. Use SUMIFS instead of SUMPRODUCT where possible
3. Avoid volatile functions (INDIRECT, OFFSET)
4. Use specific ranges instead of entire columns
5. Split calculations:
6. Divide into multiple sheets
7. Calculate in stages
8. Contact support for enterprise calculation limits

API Errors¶

401 Unauthorized¶

Cause: Invalid or expired authentication

Solutions:

1. Check token validity:
2. JWT tokens expire after 1 hour
3. Refresh the token using the refresh endpoint
4. Verify API key:
5. Check the key is correct
6. Verify the key has not been revoked
7. Check header format:

   Authorization: Bearer <token>
   # or
   X-API-Key: <api_key>
   

403 Forbidden¶

Cause: Insufficient permissions

Solutions:

1. Check user role:
2. Verify your role has permission for the action
3. Contact admin to upgrade role if needed
4. Check resource ownership:
5. You can only access resources in your tenant
6. Verify the workbook/resource ID is correct
7. Check API key scope:
8. Some API keys have limited scopes
9. Create a new key with required permissions

404 Not Found¶

Cause: Resource does not exist

Solutions:

1. Verify the resource ID - Check for typos
2. Check if deleted - Resource may have been removed
3. Verify tenant context - Resource must be in your tenant
4. Check API endpoint - Verify the URL is correct

429 Too Many Requests¶

Cause: Rate limit exceeded

Solutions:

1. Implement exponential backoff:

   import time
   
   for attempt in range(5):
       response = make_request()
       if response.status_code == 429:
           wait_time = 2 ** attempt
           time.sleep(wait_time)
       else:
           break
   

2. Reduce request frequency
3. Use batch endpoints for multiple operations
4. Upgrade subscription for higher limits

500 Internal Server Error¶

Cause: Server-side error

Solutions:

1. Retry the request - May be temporary
2. Check request body - Ensure valid JSON
3. Reduce request size - Large payloads may fail
4. Contact support with:
5. Timestamp of error
6. Request details
7. Error message

Performance Issues¶

Workbook Takes Long to Load¶

Possible causes:

Calculations Are Slow¶

Optimization steps:

1. Use efficient functions:

   # Slower
   =SUMPRODUCT((A:A="Active")*(B:B))
   
   # Faster
   =SUMIF(A:A, "Active", B:B)
   

2. Avoid entire column references:

   # Slower
   =SUM(A:A)
   
   # Faster
   =SUM(A1:A10000)
   

3. Reduce cross-sheet references:

4. Consolidate related data on same sheet

5. Use helper columns instead of repeated lookups

6. Use XLOOKUP instead of VLOOKUP:

7. XLOOKUP is optimized for large datasets

Dashboard Loads Slowly¶

Solutions:

1. Reduce widget count - Remove unused widgets
2. Filter data - Show only relevant portfolios
3. Shorten time period - Reduce historical data displayed
4. Clear browser cache
5. Try a different browser

Browser Issues¶

Page Not Loading¶

Solutions:

1. Check internet connection
2. Clear browser cache and cookies
3. Try incognito/private mode
4. Try a different browser
5. Check for browser extensions blocking content
6. Verify browser is supported (Chrome, Firefox, Safari, Edge 90+)

Features Not Working¶

Solutions:

1. Enable JavaScript - Required for CalcBridge
2. Disable ad blockers - May block API calls
3. Check console for errors - Press F12 > Console tab
4. Update browser to latest version

Display Issues¶

Solutions:

1. Zoom level - Reset to 100%
2. Clear cache - Cached CSS may be outdated
3. Try different browser - Cross-browser testing
4. Check screen resolution - Minimum 1280x720 recommended

Common Error Messages¶

Getting More Help¶

If your issue is not resolved:

1. Search documentation - Use the search bar
2. Check FAQ - See FAQ
3. Contact support:
4. Email: support@calcbridge.io
5. Include: account email, steps to reproduce, error messages
6. Report bugs:
7. GitHub: Issues
8. Include: browser, OS, screenshots

Diagnostic Information¶

When contacting support, include:

Browser: Chrome 120.0.6099.71
OS: macOS 14.2
CalcBridge Version: 1.1.0
Timestamp: 2025-01-15T10:30:00Z
Error Code: ERR_CALC_TIMEOUT
Request ID: req_abc123xyz

Find this information: - Click ? > About for version - Browser DevTools > Console for errors - Network tab for request IDs