PolyHedra / docs /ERROR_HANDLING.md
yf176
Deploy Polyhedra to HF Spaces
891fe52
|
Raw History Blame Contribute Delete
6.61 kB

Error Handling Guide

This document describes how Polyhedra handles errors and provides guidance for error recovery.

Error Categories

1. Network Errors

API Connection Failures:

Error: "Semantic Scholar API error: 503 - Service temporarily unavailable"
Recovery: Wait a few minutes and retry the search

Rate Limiting:

Error: "Failed after 3 retries due to rate limiting"
Recovery: Wait 60 seconds before making another request
Note: Polyhedra automatically retries with exponential backoff

Timeout:

Error: "HTTP error occurred: Timeout"
Recovery: Check internet connection and retry

DNS Failure:

Error: "HTTP error occurred: DNSError"
Recovery: Check network connectivity

2. File System Errors

Permission Denied:

Error: "Permission denied: /path/to/file"
Recovery: Check file/directory permissions

File Not Found:

Response: {"contents": {}, "missing": ["file.md"]}
Recovery: Check file path spelling and existence
Note: Missing files are reported but don't cause failures

Directory Creation Failed:

Error: "Cannot create directory: Permission denied"
Recovery: Check parent directory permissions or use different location

3. Validation Errors

Invalid BibTeX Format:

Error: "Invalid BibTeX format: Expected @ symbol"
Recovery: Validate BibTeX syntax using online validator

Missing Required Fields:

Error: "BibTeX entry missing required ID field"
Recovery: Ensure BibTeX entry has proper citation key

Empty Input:

Error: "Query cannot be empty"
Recovery: Provide a non-empty search query

Invalid Parameters:

Error: "Limit must be between 1 and 100"
Recovery: Adjust parameter to valid range

Missing Title in Paper:

Error: "Paper missing required 'title' field"
Recovery: Ensure papers.json entries have title field

4. State Errors

RAG Not Indexed:

Error: "Papers not indexed. Run index_papers first."
Recovery: Run index_papers tool before querying

Papers File Missing:

Error: "Papers file not found: literature/papers.json"
Recovery: Create literature/papers.json or specify correct path

Empty Papers List:

Error: "Cannot index empty papers list"
Recovery: Add papers to papers.json before indexing

Error Response Format

All errors are returned in consistent JSON format:

{
  "error": "Description of what went wrong",
  "tool": "tool_name",
  "details": "Additional context (optional)"
}

Graceful Degradation

Multiple File Operations

When reading multiple files, Polyhedra processes all valid files and reports missing ones:

{
  "contents": {
    "file1.md": "content of file 1",
    "file2.md": "content of file 2"
  },
  "missing": ["file3.md", "file4.md"]
}

Partial Citation Processing

When adding multiple citations:

  • Valid citations are added
  • Invalid citations are reported
  • Process continues for remaining citations

Paper Search with Filters

If no papers match filters:

[]

Empty array indicates no matches (not an error)

Retry Strategy

Automatic Retries

Polyhedra automatically retries network operations:

Configuration:

  • Max retries: 3
  • Retry delay: 1 second (first), 2 seconds (second), 4 seconds (third)
  • Only retries on: 429 (rate limit), timeouts, connection errors

Not Retried:

  • 400 Bad Request (client error)
  • 401 Unauthorized
  • 404 Not Found
  • Validation errors

Manual Retry Guidance

For user-level retries:

  1. Rate Limiting: Wait 60 seconds
  2. Network Issues: Check connectivity, retry immediately
  3. Service Unavailable: Wait 5-10 minutes
  4. Validation Errors: Fix input, retry immediately

Error Prevention

Best Practices

  1. Before Querying Similar Papers:

    • Run index_papers first
    • Verify papers.json exists
  2. Before Adding Citations:

    • Validate BibTeX format
    • Ensure citation key is unique
  3. Before Writing Files:

    • Check parent directory exists
    • Verify write permissions
  4. For Paper Searches:

    • Keep queries specific but not too narrow
    • Use reasonable limits (10-50)
    • Apply year filters to reduce results

Debugging Errors

Enable Verbose Logging

Set environment variable:

export POLYHEDRA_LOG_LEVEL=DEBUG

Common Issues and Solutions

"No tools available in IDE"

  • Check MCP configuration file location
  • Restart IDE completely
  • Verify Polyhedra is installed: pip list | grep polyhedra

"Tool execution failed"

  • Check you're in a valid project directory
  • Verify required files exist (papers.json, references.bib)
  • Check file permissions

"Connection timeout"

  • Check internet connectivity
  • Verify Semantic Scholar API is accessible
  • Try with VPN if behind firewall

"Invalid BibTeX"

  • Use online BibTeX validator
  • Check for missing commas, braces
  • Ensure citation key follows format

Error Logging

Log Locations

Development:

  • Console output (stderr)

Production:

  • System logs (varies by OS)
  • IDE error console

Log Levels

  • ERROR: Critical failures requiring attention
  • WARNING: Issues that don't prevent operation
  • INFO: Normal operation messages
  • DEBUG: Detailed troubleshooting information

Error Recovery Examples

Example 1: Handle Missing Files

# IDE Chat Request
"Read files: paper/intro.md, paper/method.md, missing.md"

# Response
{
  "contents": {
    "paper/intro.md": "# Introduction...",
    "paper/method.md": "# Method..."
  },
  "missing": ["missing.md"]
}

# Recovery Action
Create missing.md or continue with available files

Example 2: Rate Limit Recovery

# First request succeeds
search_papers("machine learning", limit=10)

# Second request hits rate limit
Error: "Failed after 3 retries due to rate limiting"

# Recovery
Wait 60 seconds
Retry search_papers("deep learning", limit=5)
Success!

Example 3: Invalid Citation Recovery

# Attempt to add invalid BibTeX
add_citation("@article invalid")

# Response
{
  "error": "Invalid BibTeX format: Expected '{'",
  "tool": "add_citation"
}

# Recovery
# Fix BibTeX format
add_citation("@article{key2021, title={Test}, year={2021}}")

# Success!
{
  "key": "key2021",
  "added": true,
  "message": "Citation 'key2021' added"
}

Support

For unresolved errors:

  1. Check this guide for similar issues
  2. Review logs for detailed error messages
  3. Consult API documentation for service-specific errors
  4. Report bugs: https://github.com/polyhedra/polyhedra/issues