Skip to content

Troubleshoot

How to troubleshoot in QField

When encountering issues or unexpected behavior in QField, the application provides a set of tools to help you diagnose and report problems. This guide will walk you through how to use these tools to troubleshoot effectively.

Accessing the Troubleshooting Tools

To access the troubleshooting and logging tools within QField:

  1. Open your project in QField.
  2. Tap the menu icon with the three horizontal lines on the top-left corner to reveal the side dashboard.
  3. Tap the three-dotted menu button.
  4. Select Message Log from the menu.

This will open the main screen for all troubleshooting utilities.

Understanding the Message Log

The Message Log displays a real-time log of events, warnings, and errors that occur while QField is active.

  • Reviewing Issues: If you notice any problems with your project (not all layers within the project are loading or features are not saved correctly) the Message Log is the first place to check. It often contains specific error messages that can help to identify the cause of the problem.
  • Copying Messages: To get more details or to share an error message, tap on the according entry in the log. This will copy the message directly to the clipboard of your device.

Advanced Troubleshooting

For more complex issues, QField provides additional tools to gather more detailed information about your device and the configuration of a specific project.

Profiling Application Performance

The Log runtime profile button captures a snapshot of the application's performance at that moment. This includes information about your current project.

When to use it: If you are experiencing slow performance, lagging, or freezing, generating a runtime profile can provide valuable data to you and the developers to understand how QField is interacting with your project and layers.

Submitting a Bug Report

To easily receive support from the QField development team is by sending the application logs of your device.

  • Send the application log: This button packages the detailed application log files and directly sends them to the QField development team. When you send the logs, you will be asked to add a description of the issue.

  • Provide Context: Please describe the problem you are experiencing providing as much context as possible. Include a step by step description of what you did until the issue occurred. Do not forget to mention the version of QField, QFieldSync and QGIS that you were using.

  • Reference Existing Issues: If you have already opened a discussion or a bug report on the community's platform, include the link in your message. This helps the developers to link your log files to the appropriate report.

Managing the Log

  • Clearing the Log: The Clear message log button will erase all current messages in the log. This is helpful when you want to isolate a specific issue. By clearing the log before you perform an action that causes a problem, you can ensure that the subsequent log messages are relevant to that specific issue.

Contributing to QField's Improvement

You can help to improve the stability and performance of QField by enabling the Send anonymized metrics option.

By turning this on, you allow the QField team to collect data about how the app is used and where it might be encountering problems on a wider range of devices and scenarios. Sending these metrics does not include any personal information. This information is crucial for identifying and fixing bugs and for making informed decisions about future development priorities.