Troubleshooting Guide
Relevant source files
The following files were used as context for generating this wiki page:
The Troubleshooting Guide provides a structured approach to diagnosing and resolving issues within the Nextcloud CAD Viewer application. It covers lifecycle stages from installation and environment setup to runtime file rendering and performance optimization. This guide is intended for administrators maintaining the Nextcloud instance and developers contributing to the project.
Key areas of focus include server-side environment validation (PHP and Nextcloud versions), frontend asset integrity, and client-side browser compatibility (WebGL requirements). Users encountering issues should first verify their environment against the Requirements and Installation Guide.
Sources: wiki/Troubleshooting.md:1-12, README.md:120-125
Installation and Enabling Issues
Issues during the initial setup phase typically involve directory permissions, version mismatches, or failed asset compilation.
App Not Recognized or Enabling Fails
If the CAD Viewer does not appear in the Nextcloud Apps page or the "Enable" button fails, verify the directory structure and permissions. The app must reside in the apps/cad_viewer directory. Version compatibility is strict; the app requires Nextcloud 33 and PHP 8.2+ (recommended 8.5 for specific environments).
Sources: wiki/Troubleshooting.md:17-38, wiki/Installation-Guide.md:18-24, appinfo/info.xml:29-32
The diagram above illustrates the validation logic required when the app fails to enable through the web interface.
Sources: wiki/Troubleshooting.md:21-68, wiki/Installation-Guide.md:122-130
Build and Asset Errors
For manual or Git-based installations, frontend assets must be built using Node.js (version 24+). Errors during npm run build are often caused by dependency conflicts or environment issues.
Sources: AGENTS.md:21-25, README.md:139-145
| Symptom | Probable Cause | Recommended Action |
|---|---|---|
npm run build fails | Dependency conflicts | Use npm install --legacy-peer-deps |
| Missing node_modules | Network/Proxy block | Configure npm config set proxy |
| Compilation errors | Incorrect Node version | Ensure Node.js >= 24 |
Sources: AGENTS.md:21-25, wiki/Troubleshooting.md:46-60
File Loading and Rendering Issues
The CAD Viewer utilizes WebGL for client-side rendering. Failure to load files often stems from MIME type misconfiguration, permission errors, or browser limitations.
Initialization Flow
The application initializes by retrieving the fileId from the container dataset or URL parameters before fetching content from the internal API.
Sources: src/App.vue:35-55
Sources: src/App.vue:35-65
MIME Type and File Association
If clicking a file does nothing, the web server may not be serving the CAD files with the correct headers.
- DWG MIME Types:
application/acad,image/vnd.dwg,application/dwg - DXF MIME Types:
image/vnd.dxf,application/dxf
Sources: wiki/Installation-Guide.md:178-195, tests/unit/cadLoader.spec.ts:5-18
Rendering Errors (Blank Screen)
A blank screen or "WebGL not supported" error indicates client-side hardware or browser issues. Users should visit https://get.webgl.org/ to verify WebGL 2.0 support. Hardware acceleration must be enabled in the browser settings.
Sources: wiki/Troubleshooting.md:143-155, wiki/Requirements.md:95-110
Performance and Resource Constraints
High memory usage or laggy navigation occurs when handling large drawings (>50MB) or when server limits are too restrictive.
Server-Side Optimization
For large file transfers, PHP limits must be increased in php.ini:
memory_limit = 1024M
max_execution_time = 300
upload_max_filesize = 500M
post_max_size = 500M
Sources: wiki/Installation-Guide.md:200-205, wiki/Troubleshooting.md:247-253
Client-Side Performance
- Memory Usage: Large files consume significant browser RAM. Closing unused tabs is recommended.
- Navigation: Slow zoom/pan can be mitigated by disabling unnecessary layers in the Layer Manager.
- Mobile: Performance is lower on mobile devices; landscape orientation and tablet hardware are recommended for complex drawings.
Sources: wiki/Troubleshooting.md:185-210, wiki/User-Guide.md:225-235
Common Error Messages
| Message | Context | Solution |
|---|---|---|
| "Failed to load CAD viewer" | Vue component initialization error | Check browser console; retry load button |
| "Invalid file format" | Corruption or unsupported DWG version | Re-upload; verify version (R14 to 2018 supported) |
| "Access denied" | Nextcloud file permissions | Check user read permissions for the specific file |
| "Out of memory" | Browser/System limit reached | Optimize CAD file (PURGE command in AutoCAD) |
Sources: src/App.vue:68-72, wiki/Troubleshooting.md:301-315, wiki/Requirements.md:135-145
Conclusion
Troubleshooting the Nextcloud CAD Viewer requires a cross-tier approach, verifying the PHP/Nextcloud environment on the server and the WebGL capabilities on the client. Most issues are resolved by ensuring correct file permissions, configuring appropriate MIME types, and meeting the minimum Node.js requirements for asset builds. For persistent issues, administrators should consult the Nextcloud logs (data/nextcloud.log) and the browser's developer console.