Troubleshooting

This page covers common issues and their solutions.

Display Issues

Entities disappear after moving

The internal spatial index may have stale position data. The application handles index invalidation automatically, but if entities become invisible after an operation, type ZOOM E in the command line to zoom to extents and refresh the display.

Colors look wrong or lines are invisible on a dark background

Line styles set to use ByLayer colors may default to black, which is invisible against a dark canvas background. Check that line styles in the Style Libraries use colors appropriate for your background setting. You can change the canvas background color in Settings.

Resource and File Issues

Hatch patterns not rendering

TunnelCAD requires a resources folder located next to the application executable. This folder must contain the hatch pattern files (.pat), linetype files (.lin), and font files (.shx). If the folder is missing or incomplete, hatches will fail to render without an error message.

Point cloud not loading

Point cloud support requires external libraries in the application directory:

  • Linux: libE57CWrapper.so and liblaszip.so

  • Windows: the corresponding .dll files alongside the .exe

If these libraries are missing, point cloud import will fail.

Settings not saving

Verify that the application has write permissions to the settings file location:

  • Linux: ~/.config/TunnelCAD/settings.json

  • Windows: %APPDATA%\TunnelCAD\settings.json

If the directory does not exist, TunnelCAD creates it on first run. File permission issues can prevent this.

Import and Export Issues

LandXML import missing data

Ensure the correct items are checked in the import dialog before proceeding. Some data – such as widening, cant, line definitions, and DR measurements – is stored in TunnelCAD-specific <Feature> extensions within the LandXML file. Files exported from other software will not contain these extensions, so only standard alignment, profile, and cross-section geometry will be available.

TCM conversion shows garbled characters

Older TCM files may use Windows-1253 (Greek) character encoding. The converter performs automatic cleanup of non-UTF8 characters, but some characters may not convert perfectly. Review the converted project for any remaining encoding artifacts in names and descriptions.

Template and Section Issues

Templates not applying to new sections

Templates are assigned to chainage ranges via Station Definitions in the project tree. If a newly created section does not receive the expected template, check that a Station Definition exists whose chainage range covers that section’s station. Sections outside all defined ranges will have no template assigned.

Debug Logging

If you encounter an issue that requires deeper investigation, enable debug logging:

  1. Open the settings file (settings.json at the path listed above) in a text editor

  2. Set "debugLog": true

  3. Restart TunnelCAD

The application writes timestamped log entries to iqcad_debug.log in the same directory as the executable. The log flushes on every write, so entries are preserved even if the application crashes. Share this file when reporting issues.