Troubleshoot

This page contains known issues that can occur while using the Survey123 field app to complete a survey and provides suggestions to resolve them.

Send error

The following error may appear if your completed survey was unable to be submitted:

Send error message

Tap Yes in the message box to go back and edit your answers before submitting. Tapping No closes the error message and returns you to the outbox.

Some common send errors are listed in the following table:

Error numberError descriptionDiagnosis

None

Feature service requirements not met. supportsApplyEditsWithGlobalIds must be true.

The feature layer does not have the supportsApplyEditsWithGlobalIds property set to true. Enable supportsApplyEditsWithGlobalIds using the steps in this blog post.

400

Invalid URL

The feature layer specified when the form was loaded is no longer present, which can happen due to a schema-altering change to the form. The only solution to this is to manually migrate the data using recovery techniques.

498

Invalid token

The token that the field app is attempting to pass to ArcGIS is being rejected. Often, this is because the token the app is trying to pass has expired. In this case, repeat the action, and the error shouldn't recur.

1000

String or binary data would be truncated

The result of a question is too long for the field in the feature layer. Edit your answer to fit the character limit.

1000

Invalid column name 'Shape__Extents'

The point being submitted is outside the full extent of the feature layer. If this is a repeated problem, and the location you're attempting to submit is correct, the feature survey should be republished with a larger extent. However, be aware that doing this will cause you to lose the information already saved in the feature layer.

1003

Survey123 Operation rolled back

This can occur when a survey has hidden or calculate questions with the wrong data type. The data type of a calculation is dependent on the data type of each element of the calculation. The XLSForm default binding type for hidden and calculate questions is string. To overwrite this default, enter the required type (for example, int or decimal) in the bind::type column for your question.

1019

The specified feature could not be updated

This can occur when attempting to send an edited survey that contains a repeat in versions of the Survey123 field app that do not support it. Editing of surveys that contain repeats is supported in the Survey123 field app at version 2.4 and later.

Inbox error

The error You don't have permissions to access this resource or perform this operation. Code 403 may appear when a user other than the survey author refreshes the Inbox. When the inbox is enabled before the survey is first published, the required permissions are enabled by default. If the survey author first publishes the survey with the inbox disabled and enables it later, they must enable Delete or Update in the feature layer's settings, to ensure the required permissions are updated.

Unsupported spatial reference when downloading maps

Unsupported spatial reference in Download Maps

This message may appear in the Survey123 field app when attempting to download a basemap to the device. Survey123 requires that your basemaps use the Web Mercator Auxiliary Sphere spatial reference. This is the same spatial reference used by Esri's World Topographic and other basemaps. If the Survey123 field app detects that your survey is associated with an offline basemap that is not the Web Mercator Auxiliary Sphere projection or is incorrect or missing, you get a warning. Note that in some cases, offline basemaps may be missing information about the spatial reference. In these cases, the warning message indicates that the spatial reference is none. An offline basemap with an unknown (listed as none) spatial reference may still work correctly in Survey123 if the actual basemap was built using the Web Mercator Auxiliary Sphere projection.

Autosave

If your device or app crashes while you're completing a survey, the survey response is recoverable. Any change in focus in the survey—for example, the user activating a new question—triggers the contents of all previously completed questions being written to an autosave.json file. This file exists in the My Surveys folder during survey entry and is used if the app exits abnormally before the survey could be properly written back to the database.

On startup, the Survey123 field app checks for the presence of the autosave file. If found, you are notified that a survey response has been recovered, displaying the survey name and instance name.

Survey Recovered dialog box

Tapping Discard survey deletes the autosave.json file, losing the recovered data. Continue survey opens the survey, populating it with the recovered data. The autosave.json file is automatically deleted when a survey is successfully completed or saved as a draft.

Note:

The recovered survey includes all previously completed questions except for the one being completed on crashing. This is because the trigger for saving a question is the focus change.

If you don't want the survey to be automatically saved every time you start a new question, you can use the bind::saveIncomplete column to add save milestones to your survey. Set the value to true for each question that you want to trigger a save. You can apply the bind::saveIncomplete column to the following question types:

  • Text
  • Integer
  • Time
  • Date
  • Date-time
  • Select multiple
  • Select one

Enable diagnostic logging

If you observe error messages that aren't listed in this topic, or other unexpected behavior, it may be useful to record a log of information from the Survey123 field app to share with someone else (such as Esri Technical Support staff) to troubleshoot.

To enable logging, open the menu on the app's home page, tap Settings, and tap the Diagnostics tab.

Logging in the

To capture messages to a file, tap the Logging toggle button to enable logging. The Log output location option is automatically populated with the default log file location. You can edit this file path. To capture messages to a syslog-compatible console online, enter its URL in the Log output location text box in place of the log file location.

Log files can be shared or sent by email. When you choose to send the log by email from the app, the app version number, operating system name, and the system locale will be included in the email body and the log will be included as an attachment.

Note:

For real-time logging, the Diagnostics tab displays any instances of the AppStudio console open on your network. A searching circle symbol appears on the Diagnostics tab until it has found a running AppStudio console. If you first select an AppStudio console, and tap the Logging toggle button to enable logging, logging information appears in that console. For more information, see Capture console output in the ArcGIS AppStudio help.

Recover data using desktop field app

There are times when you can't send surveys from your mobile device—either wireless internet connectivity isn't possible or something unexpected has happened to your mobile or server database.

Your survey data is stored on your mobile device as a .sqlite database. You can copy and edit this database to aid data recovery.

If your issue is internet connectivity from your mobile device, you can copy your .sqlite database to your desktop, open it in the desktop version of the Survey123 field app, and send your surveys.

Before starting the following steps, download the survey from which you are attempting to recover results to your desktop version of the Survey123 field app.

  1. Copy the .sqlite file from your device.
    Note:

    If you're using an iOS device, you'll need to use an iOS file browser app. On macOS version 10.15 Catalina or later, you can use Finder as a file browser. On earlier versions of macOS, or on Windows, you can use iTunes or another file browser app. The file is automatically stored in Survey123/ArcGIS/My Surveys/Databases.

    If you are using an Android device, the file is automatically stored in the app specific storage location of Android/data/com.esri.survey123/files/ArcGIS/My Surveys/Databases. Prior to Survey123 version 3.12 files were stored in the internal storage location of ArcGIS/My Surveys/Databases.

  2. Paste this .sqlite file into the equivalent Survey123 folder on your desktop (for example, on Windows, it would be C:\Users\<username>\ArcGIS\My Surveys\Databases).
    Note:

    If you've already collected surveys on the desktop, you may already have a database there. If so, you can save this into a subfolder, or rename the database folder and create one for the copied files. If you don't have completed surveys you need to send, you can safely delete the existing database on the desktop.

  3. If your survey has image, audio, or file questions, also copy the My Survey Attachments folder from your device to your desktop.
  4. Open the Survey123 field app, go to Settings > Advanced and tap the Fix Database button.
  5. Browse to your survey and confirm that there are surveys ready to send.
  6. Send your surveys.

Recover data using desktop field app and manual edits to the database

Sometimes the Fix Database tool may not recover your data, or you may have other issues with your database. In these cases, you can also manually modify the paths stored in the .sqlite database.

The following steps describe how to manually modify your .sqlite database.

    Before starting these steps, download the survey from which you are attempting to recover results to your desktop version of the Survey123 field app.
  1. Copy the .sqlite file from your device. The file is located in ArcGIS/My Surveys/Databases.
  2. Paste this .sqlite file into the equivalent Survey123 folder on your desktop (for example, on Windows, it would be C:\Users\<username>\ArcGIS\My Surveys\Databases).
  3. Open the .sqlite database in a database editor. An example editor is DB Browser for SQLite.
  4. If you're using DB Browser for SQLite, look at the path column on the Browse Data tab. You'll see that each record represents a single completed survey, and each has a path reference to the device where it was collected. To send the surveys on the desktop, you need to change the path to match the survey data path of the desktop.
  5. To change the record, go to the Execute SQL tab and type the following using your own local path details:

    UPDATE Surveys SET path = REPLACE (path,"/sdcard", "C:/Users/Me") where path LIKE "/sdcard%"

  6. Go back to the Browse Data tab and confirm that the paths have changed.
  7. Close the SQLite application.
  8. Open the Survey123 field app and confirm that there are now a number of surveys ready to send (there should be a red number in the corner of the survey thumbnail).
  9. Send your surveys.