FAQ and Troubleshooting

This page answers common questions and lists the solutions to common problems. Start with the log file. It holds the error details that you need for a bug report.

Quick checks

1. Check the Python version. FlatCAM Evo needs Python 3.10 or newer.
2. Check the log file. See Where the program keeps its data.
3. Check the graphics driver. See OpenGL or graphics errors.
4. Check the units of the project and of the file. See Units look wrong.

Where the program keeps its data

FlatCAM Evo keeps its data in a data folder.

System	Data folder
Windows	%APPDATA%\FlatCAM
Linux and macOS	~/.FlatCAM

The data folder holds:

• The preferences file current_defaults.FlatConfig.
• The Tools Database.
• The recent files lists.
• The log file log.txt.
• Your own preprocessors, in the preprocessors/ folder.

Use the Open Pref Folder button in the Preferences tab to open the folder.

Portable mode (Windows)

Set portable=True in config/configuration.txt, in the program folder. FlatCAM Evo then keeps its data in a config folder next to the program. Use this mode on a USB drive.

Own data folder

Set the environment variable FLATCAM_DATA_PATH to a folder. FlatCAM Evo keeps its data there. This overrides the default folder and the portable mode. Use it for a second installation or for a test with fresh settings.

Log file and error log

• The log file is log.txt in the data folder. It holds the messages and the tracebacks of the program.
• The View > Error Log menu item shows the errors of the session.
• Attach the log file to a bug report.

The Report a bug item is in the Help menu. Give the version, your system, the steps and the log.

OpenGL or graphics errors

The message OpenGL initialization failed means that the 2D and 3D canvas could not start OpenGL.

Try these steps in this order:

1. Install or update the graphics driver from your GPU vendor or from your operating system. Restart FlatCAM Evo.
2. For a remote desktop session or a virtual machine, check that the session exposes OpenGL. Turn on the graphics acceleration of the virtual machine. Install the graphics drivers of the guest system.
3. Try a local desktop session to find out whether the problem is the remote session.
4. If it still fails, open the log file. Report the error with your operating system, GPU, driver version and the remote or virtual setup in the issue tracker.

FlatCAM Evo needs OpenGL for the canvas. See the requirements in Installation.

Preferences

Reset the preferences to the factory values

1. Open the Preferences tab with Shift+P.
2. Click Restore Defaults. The form shows the factory values.
3. Click Save to write the values to the preferences file. Or click Apply to use them without saving to a file.

Use Restore Defaults only when you want to lose your changes.

Reset the window layout and the style

Click Clear GUI Settings in the Preferences tab. This clears the layout, the style and the GUI state.

To bring back the layout only, use View > Restore Layout.

Save, load and export the preferences

• File > Backup > Save Preferences: saves the current preferences.
• File > Backup > Export Preferences to file: writes the preferences to a file.
• File > Backup > Import Preferences from file: loads a preferences file.

Units look wrong

• The units belong to the project. The status bar shows the units of the active project, for example [mm].
• A Gerber or Excellon file gives its units in its header. A file without a unit setting uses the default unit of the Gerber or Excellon import preferences. See Importing Files.
• If the paths are 25.4 times too big or too small, the units of the file and the units of the project do not match.
• Check the units before you generate the paths. See Getting Started.

Slow geometry or a slow canvas

• Turn off the plots of the objects that you do not need. Use View > Disable non-selected (Alt+4) or View > Disable all (Alt+2).
• Large Gerber files with many shapes take longer to process. Simplify the shapes with the Simplification tool before you generate the paths.
• The Gerber fusion is faster with the optional pyclipr package. Install it from requirements-optional.txt.
• The path optimization needs the ortools package and a 64-bit Python. Without it, the path optimization is not available.
• To stop a long task, use Ctrl+Alt+X (Abort current task (gracefully)).

Installation problems

The program does not start with an older Python

FlatCAM Evo writes a message to the log file and exits when the Python version is lower than 3.10. Install Python 3.10 or newer, then start the program again. See Installation.

gdal does not install

• Windows: install a GDAL wheel for your Python version from cgohlke/geospatial-wheels. Then run the requirements.txt command again.
• Linux and macOS: install the GDAL system library first. Then run gdal==$(gdal-config --version) in the virtual environment. Or use the conda environment.

The Image Import plugin is missing

The Image Import plugin needs the rasterio package with GDAL. The tracing mode also needs vtracer. Install them in the active environment, as described in Installation. Restart FlatCAM Evo.

The path optimization is missing

Install ortools and use a 64-bit Python.

Files

A file does not open

• Check that the file is a Gerber or Excellon file for the right layer.
• Check that the file is complete. A cut-off file gives an error.
• Check the log file for the error message.

Files open in the window that is already running

This is normal. When you open a file from the file browser, FlatCAM Evo hands the file to the running window. The second process ends.

The copper and the drills do not line up

• Check the origin and the units of both files.
• Check the Excellon format settings (number of digits, zeros) in the Excellon preferences.
• Use Align Objects to line up the objects. See Align Objects.

Machine problems

The G-code does not run on the machine

• Check the preprocessor of the CNC job. Choose the preprocessor of your machine.
• Check the tool change position and the travel height.
• Open the saved G-code file in a text editor and check it before you run it.

The tool does not change between the drill sizes

Turn on the Tool change Z check box in the Drilling plugin. If it is off, all selected holes are drilled with the parameters of the first tool. See Drilling.

Updates

• Help > Check for Updates finds and installs a new release.
• If a new release does not work, Help > Revert to Previous Version restores the previous installation.
• FlatCAM Evo 1.0 cannot update itself. Install version 1.01 or newer with the installer one time. See Updates.

Other questions

Where is the Tcl shell?

Click Plugins > Command Line (S). The shell opens at the bottom of the window. See Tcl Shell.

Can I run FlatCAM Evo without a window?

Yes. Use --headless on the command line. See Command Line and Headless.

Where are the keyboard shortcuts?

Press F3 in the program. See Keyboard Shortcuts.

See also

• Installation
• Getting Started
• User Interface
• Preferences Overview
• Updates
• Command Line and Headless