|
Download docs/ERROR_HANDLING.md from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 6.61 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/ERROR_HANDLING.md
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/docs/ERROR_HANDLING.md
-
curl -L -o ERROR_HANDLING.md https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/ERROR_HANDLING.md
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: | |
| ```json | |
| { | |
| "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: | |
| ```json | |
| { | |
| "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: | |
| ```json | |
| [] | |
| ``` | |
| 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: | |
| ```bash | |
| 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 | |
| ```python | |
| # 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 | |
| ```python | |
| # 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 | |
| ```python | |
| # 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 | |