Troubleshoot

Survey123 Connect will convert your forms designed using the XLSForm specification into an XForm to be used in Survey123 and publish them to either ArcGIS Online or ArcGIS Enterprise. Some issues may arise during this process.

Form conversion errors

When you create a new survey in Survey123 Connect, you use the XLSForm specification to design your form using a spreadsheet. Survey123 Connect converts the spreadsheet into an XForm, allowing you to preview your survey as it will appear in Survey123.

The conversion occurs after you do the following:

  1. Save the changes in your spreadsheet.
  2. Click the Update button in Survey123 Connect.

If there is an issue with your survey, you'll receive an error from the form conversion service. In the following example, the error message explains that the issue is with the name entry called last name. In this case, the entry has a space in it. The space should be removed or replaced with an underscore or dash.

Error message

Some common form errors are listed in the following table:

Error descriptionDiagnosis

Error converting XLSForm

In the example above, this error highlighted the question called last name. In that case, the error is the space in the name column. Another common error that will result in this message is when non-ASCII characters are used in the name column of either the survey or choices worksheet. ASCII characters can be used in the label column but not in the name column.

[row : 2] List name not in choices sheet: [JobType]

This error tells you that one of your select_one or select_multiple questions is referencing a list that does not exist in the choices worksheet. In this example, the brackets should be removed.

There should be choices for this question.

This error tells you that one of your select_one or select_multiple questions that has the additional parameter of or_other as part of the type also has a choice filter defined. Select questions that include the option of entering a value of Other cannot be used in a cascading selection.

Network errors

If you have trouble accessing the form conversion service, you'll receive an error similar to the following:

Network error message

Some common network errors are listed in the following table:

Error numberError descriptionDiagnosis

-1

Cannot open C:/Users/Username/ArcGIS/My Survey Designs/Form 1/Form 1.xlsx

Excel may have a lock on your file. Ensure the survey is not open by another application or user.

3

Host survey123.arcgis.com not found

You are running a previous version of Survey123 Connect. Upgrade to the latest version.

6

SSL handshake failed

There are a number of issues that could cause SSL handshake failures, such as the following:

  • Check that the certificate is valid, including details such as expiration date, common name, and issuer.
  • Check that the root certificate in the certificate chain is correct and deployed to all devices.
  • Check the intermediate certificates in the certificate chain.
  • Check that the encryption algorithm used in the certificate is supported by the device. The typically used algorithm is SHA256.

You can test the SSL certificates used in a web server using an online tester such as SSL Labs.

99

Connection timed out

Sometimes observed when working with very large surveys. Try again.

202

Error downloading https://survey123.esri.com/api/xls2xform - server replied: Forbidden

Any error that has esri.com in the message is pointing to the old server. Upgrade to the latest version.

203

Error downloading https://survey123.esri.com/api/xls2xform - server replied: Not Found

Any error that has esri.com in the message is pointing to the old server. Upgrade to the latest version.

401

Error downloading https://survey123.arcgis.com/api/xls2xform - server replied: Internal Server Error

This error is typically triggered by expressions in the relevant or calculation columns. Use curly brackets and include a $ symbol at the beginning of the statement.

403

Error downloading https://survey123.esri.com/api/xls2xform - server replied: Service Temporarily Unavailable

Report this to Esri immediately.

498

Invalid token

The token that Survey123 Connect tried to pass to ArcGIS was not accepted. This is most often caused by a submission URL trying to pass a token to a public feature layer.

499

Error transferring https://survey123.arcgis.com/api/xls2xform - server replied: Proxy Error

The Survey123 API is unavailable or has timed out. Try again after a short period. If the issue persists, refer to the Survey123 Esri Community for more information.

On the error dialog box, you have the opportunity to capture the error to send to Esri. Add any additional information to the email that might help in debugging your issue.

Publish errors

These errors typically come from the issue of creating the items from your survey in ArcGIS.

Publish error message

Common publish errors are listed in the following table:

ErrorDiagnosis

Submission url is not compatible (Field not found)

The named field is not present in the feature layer designated by the submission URL, meaning that the survey's responses are incompatible with the survey. Either unassign the submission URL to create a new one, or ensure that your submission URL is to the correct feature layer. This error is commonly caused by the additional field that is created when using the or_other option for a select_one or select_multiple question. For more information, see Multiple choice questions.

Submission url is not compatible (Request error)

Check that the user you have signed in to Survey123 Connect as has permission to access the feature layer.

No child key field in SurveyName for parent repeat_1

This error occurs if the feature layer you're submitting to relies on Global ID parent keys that aren't present in the survey. In the Publish Options window, set Use global id parent keys in repeat relationships to true.

CREATE TABLE failed because column 'x' in table 'y' exceeds the maximum of 1024 columns

The survey you are attempting to publish has more fields than are allowed by a feature layer in an ArcGIS organization (1,024). Reduce the number of fields to less than 1,024 and publish the survey again. For more information on these limitations, see Troubleshoot in the ArcGIS Online help.

The custom feature service submission url is not compatible with this survey (The feature service does not meet the requirements for a survey with repeats - supportsApplyEditsWithGlobalIds)

The supportsApplyEditsWithGlobalIds property is set to false and needs to be true. The easiest way to do this is to enable sync when publishing your feature layer.

The custom feature service submission url is not compatible with this survey (Destination relationship not found for table)

A repeat in your survey is either incorrectly associated with a related table in the feature layer, or the table does not exist. Ensure that your repeat has the same name as the destination related table.

Portal errors

Surveys published to ArcGIS Enterprise have the limitations listed below, which are different from those published to ArcGIS Online.

  • You cannot publish surveys to ArcGIS Enterprise that use certain reserved keywords as field names, such as end (field names containing these keywords are acceptable, such as endSurvey, as long as they are not exactly the keyword). Reserved keywords are listed in the Reserved worksheet of the Survey123 XLSForm templates.
  • All field names must be lowercase when publishing to ArcGIS Enterprise.
  • The maximum number of columns that a feature layer published to a portal can contain depends on your enterprise geodatabase. See the documentation for your database management system to determine size limits. If the number of questions in your survey exceeds the column limit for your enterprise geodatabase, the workaround is to include a repeat, and set repeat_count to 1 to extend the survey over multiple tables.
  • The name of a question in the survey worksheet must be fewer than 32 characters.
  • You cannot upload Survey123 content to ArcGIS Enterprise or Portal for ArcGIS if you are not using ArcGIS Data Store.
  • When ArcGIS Enterprise is deployed in a disconnected environment, survey templates, samples, and submission URLs to ArcGIS Online feature layers do not work.
  • Submission URLs cannot be used directly with a nonfederated ArcGIS Server feature layer. A workaround is provided by registering the service with ArcGIS Online or ArcGIS Enterprise.
  • If using a multiuser geodatabase, layers can use branch versioning but not traditional versioning. Survey123 will target the default version when using a branch versioned geodatabase. For more information see Versioning types.

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 Survey123 Connect to share with someone else (such as Esri Support) to troubleshoot.

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

Logging in

To capture messages to a file, click the Logging toggle button to enable logging. The Log output location text box 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 an AppStudio console currently 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 click the Logging toggle button, logging information will start to appear in that console. For more information, see Capture console output in the ArcGIS AppStudio help.