# 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.