Troubleshooting Import Issues
If you encounter unexpected errors or empty previews when importing documentation or code, consult the resolutions below.
1. README Contains No Recognized Architecture
Symptoms
Pasting a README returns an empty preview or only a generic project title node.
Cause
The analyzer searches for:
- Fenced Mermaid blocks (````mermaid graph TD ... `````).
- Standard Markdown headings like
## Architecture,## System Design,## Components, or## Services. - Lists with technology names (e.g.
PostgreSQL,Redis,Next.js).
If the README consists solely of installation instructions (npm install) or marketing prose without architectural sections, the parser has no structural anchors to extract.
Solution
- Ensure the README has an
## Architectureor## System Designheading. - Or embed a simple Mermaid flowchart block describing the service flow.
2. Code Analyzer Does Not Detect Services
Symptoms
Uploading a project directory produces an empty preview or only a single root node.
Cause
- Manifest files (
package.json,pom.xml,requirements.txt,docker-compose.yml) were not included in the upload selection. - The project uses an unconventional custom build system or proprietary manifest not yet supported by heuristic matching.
Solution
- Make sure to upload the root directory containing your project manifests.
- Including a
docker-compose.ymlprovides the highest accuracy for multi-service architectures.
3. Large File or Browser Freezing During Code Upload
Symptoms
The browser tab stutters or becomes unresponsive when dragging a folder.
Cause
The folder contains heavy build artifacts, virtual environments, or dependency trees:
node_modules/,.git/,venv/,target/, ordist/.
Solution
- Do not drag entire dependency folders like
node_modules/. - Only upload the source directory (
src/) and top-level manifest files.
Next: Review GitHub-specific troubleshooting in GitHub Issues.