Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
The DeepCode system incorporates specialized diagnostics and error-handling mechanisms designed to maintain the integrity of the Paper2Code and Text2Web workflows. Troubleshooting within this project encompasses system-level diagnostics, LLM-based error guidance, and UI-driven recovery tools to address failures in document parsing, environment setup, and code synthesis.
Sources: ui/components.py, workflows/code_implementation_workflow.py
System Diagnostics and UI Troubleshooting
The user interface provides dedicated components for real-time system health checks and manual recovery. These tools allow developers to verify environmental dependencies and clear stale application states.
UI Troubleshooting Components
The ui/components.py file defines a system_status_component that performs automated checks on the runtime environment and critical library dependencies.
| Diagnostic Check | Purpose | Source |
|---|---|---|
| Python Version | Verifies compatible runtime environment. | ui/components.py:273 |
| Module Status | Checks for presence of streamlit, asyncio, and nest_asyncio. | ui/components.py:279-284 |
| Streamlit Context | Verifies ScriptRunContext for threading stability. | ui/components.py:293-301 |
| Event Loop | Detects active asyncio loops to prevent processing hangs. | ui/components.py:304-316 |
Common UI Issues and Resolutions
The error_troubleshooting_component provides actionable steps for common runtime errors:
- ScriptRunContext Warnings: Threading warnings that can typically be resolved by restarting the application.
- Async Processing Errors: Fallback methods are triggered automatically, but a page refresh may be required.
- File Upload Issues: Restricted to formats like PDF, DOCX, TXT, and MD with a 200MB size limit.
- Processing Timeouts: Large papers may require 5-10 minutes; wait for progress indicators to update.
- Application Reset: A manual "Reset Application State" button allows clearing
st.session_stateto recover from inconsistent states.
Sources: ui/components.py:321-356
Workflow Error Handling and Guidance
The code implementation workflow uses an iterative loop that monitors tool results for errors and provides "corrective guidance" to the LLM agent.
Automated Error Detection
The workflow manager implements _check_tool_results_for_errors, which parses JSON responses from MCP (Model Context Protocol) tools to identify status failures.
The diagram shows the logic flow for determining user-side guidance based on tool execution outcomes.
Sources: workflows/code_implementation_workflow_index.py:465-481, workflows/code_implementation_workflow.py:440-456
Corrective Guidance Patterns
When an error is detected, the system injects specific instructions to the agent to recover the implementation flow.
| Scenario | Recovery Action | Source |
|---|---|---|
| Tool Error | Review error details, fix the issue, and verify remaining file count. | workflows/code_implementation_workflow_index.py:512-525 |
| No Tool Called | Mandate the use of tools instead of pure text explanations. | workflows/code_implementation_workflow_index.py:527-542 |
| Analysis Loop | Detect repetitive analysis cycles and force progress toward implementation. | workflows/code_implementation_workflow_index.py:302-307 |
Memory and Context Management Troubleshooting
Failures in long-running sessions often stem from token limit exhaustion or context loss. The ConciseMemoryAgent mitigates these by aggressively pruning conversation history after successful file writes.
Concise Memory Logic
The agent tracks last_write_file_detected to trigger memory optimization. If the agent enters an inconsistent state, it reverts to a "Fallback Mode" summary.
Memory Diagnostic Statistics
Developers can debug the memory state using get_memory_statistics, which provides visibility into the implementation lifecycle.
- last_write_file_detected: Boolean flag indicating if the clearing trigger is active.
- should_clear_memory_next: Flag indicating the next iteration will start with a clean slate.
- compression_ratio: Calculated percentage of tokens saved during optimization.
Sources: workflows/agents/memory_agent_concise.py:596-629, workflows/agents/memory_agent_concise_index.py:596-629
Prompt-Level Troubleshooting
The prompts/code_prompts.py file contains "Critical Output Restrictions" to prevent JSON parsing errors.
- JSON Enforcement: Prompts like
PAPER_INPUT_ANALYZER_PROMPTdemand raw JSON with no markdown code blocks (```json) or preamble. - Path Type Classification: Detailed rules for classifying URLs, local files, and directories to prevent downloader failures.
- Segmented Reading: To avoid token limits, the system uses
read_document_segmentswith specificquery_typeandkeywords(e.g., "algorithm_extraction") rather than reading the entire document.
Sources: prompts/code_prompts.py:40-70, prompts/code_prompts.py:215-225
Troubleshooting in DeepCode is a multi-layered approach that combines automated environment checks with intelligent agent guidance. By leveraging the system_status_component for infrastructure health and the ConciseMemoryAgent for context stability, the system maintains a high success rate even during complex, multi-file code implementations.