Skip to main content

Troubleshoot

The following are common issues you may encounter when working with ArcGIS Velocity, along with recommended solutions. If you encounter an issue that's not addressed below, contact Esri Technical Support.

Common issues when configuring Velocity logs

The following are common issues you may encounter when configuring logs in Velocity, along with recommended solutions.

  • If you are troubleshooting errors during the installation of Velocity, it may be helpful to review the installation logs. During installation, Velocity writes logs to the following location: <Velocity install directory>/velocity_installer.log

  • If you are troubleshooting issues related to feeds, real-time analytics, or overall system performance, it is recommended that you review the query logs for more information.

Learn more about logs

Common issues when federating a Velocity site with a portal

The following are common issues you may encounter when federating a Velocity site with a portal, along with recommended solutions.

  • Velocity requires federation to a base Enterprise deployment that is at version 12.1. If you receive the following error message during the federation process, it indicates that you are using an Enterprise version that is currently not supported.

    Error message:

    ArcGIS Server must be at version(s) (12.0.0,11.5.0,11.4.0,11.3.0,11.2.0,11.1.0,11.0.0,10.9.1,10.9.0,10.8.1,10.8.0,10.7.1,10.7.0,10.6.1,10.6.0,10.5.1,10.5.0) in order to federate with Portal for ArcGIS and currently the version of ArcGIS Server '<Velocity FQDN>:7143/arcgis' is 12.1.0.

    You need access to a base Enterprise deployment at 12.1 or later to successfully complete the Velocity installation.

    Note:

    Velocity and Enterprise must be on the same version. Using different versions is not supported.

  • If you receive the following error during the process of federating Velocity to your Enterprise portal, check the username and password. You must be providing credentials for the Velocity primary site administrator account.

    Error message:

    Failed to federate ArcGIS Server site <Velocity FQDN>:7143/arcgis' with Portal for ArcGIS. Failed to generate token at ‘<Velocity FQDN>:7143/arcgis' for user<velocityAdmin>. JSONObject["token"] not found.

Velocity is not working

If part of a page is missing, clear your browser cache and cookies. This operation varies depending on the browser you use. In Google Chrome, ensure to clear since the beginning of time, and in Mozilla Firefox, clear everything.

I cannot sign in to Velocity

Contact your Enterprise administrator and verify that Velocity is installed and your user account has the correct privileges to access Velocity and perform actions, such as creating feeds and real-time analytics.

How do I determine my Velocity license level and expiration date?

To view your Velocity version, complete the following the steps:

  1. In a browser, open the Velocity app and sign in using your ArcGIS organization credentials.

  2. On the Velocity Home page, click the information icon next to the Resource Utilization option.

The installed version of Velocity is displayed.

Administrators can use the Velocity Administrator directory to view additional information including the license expiration.

Learn more about Velocity license levels

How do I reset my refresh token in Velocity?

Velocity stores a refresh token to authenticate with ArcGIS Enterprise the first time a feed or analytic is started. Velocity uses the refresh token to generate access tokens as needed to access ArcGIS Enterprise items rather than having to store the user's username and password. This makes it easier to share items in Velocity and keep users' credentials secure.

The maximum refresh token expiration time is set by the Enterprise organization, and by default, this value is 14 days. While an Enterprise administrator can change this value, it is recommended that the expiration time be set to at least seven days.

If a refresh token expires, after a year, or is otherwise invalidated by Enterprise (for example, with a change of password or security settings), you must reset the refresh token stored in Velocity. If a refresh token is invalidated by Enterprise, Velocity feeds and analytics are stopped and cannot be started. Reauthentication errors appear in the feed and analytic logs, and an email notifies you that the running feeds and analytics must be reauthenticated.

Follow the steps below to reset your refresh token to reauthenticate Velocity with Enterprise:

  1. In a browser, open the Velocity app and sign in using your ArcGIS organization credentials.

  2. From the Velocity Home page, click the information icon next to the Resource Utilization option.

  3. On the subscription information page, click the Reset Refresh Token option.

    A window appears with the option to delete your current token and register a new one.

  4. Click the Delete option to delete the existing refresh token.

    A window appears confirming the existing token was deleted.

  5. Sign in again using the same Enterprise account credentials to automatically retrieve and register a new token.

  6. Click Close once a new token is successfully registered.

  7. Restart your feeds and analytics.

You have reset the refresh token in Velocity.

Common issues when configuring certificates in Velocity

The following are common issues you may encounter when configuring certificates during the Velocity installation, along with recommended solutions.

When a client, such as Map Viewer connects to Velocity, it verifies the full certificate chain — from the server certificate through any intermediate certificates to the root CA. If any part of this chain is missing, the connection may fail or display warnings, even if the browser shows a lock icon. A common symptom of an incomplete certificate chain is an Attempting to reconnect message in Map Viewer after adding a stream layer or feed. This typically means the client cannot fully trust the certificate presented by Velocity.

Learn more about importing the server certificate and any root or intermediate certificates

After importing, ensure that Velocity is configured to use the CA-signed certificate by verifying the Web Server SSL Certificate field in the Velocity Administrator directory, machines > [machine name].

Note:

The certificate's Common Name (CN) or Subject Alternative Name (SAN) must exactly match the hostname in your Velocity URL. For example, if your Velocity URL is https://myVelocity.example.com, the certificate must include myVelocity.example.com. A certificate issued only for example.com is not accepted.

What should I provide when requesting an Esri Technical Support case?

Before submitting an Esri Technical Support case, gather your Velocity details by clicking the information icon next to the Resource Utilization option on the Home page. Ensure you have the following information ready when submitting your case:

  • Velocity version

  • Operating System (Windows or Linux)

  • Relevant log messages or error details

I cannot create a feed or real-time analytic

You cannot create items for any of the following reasons:

  • You do not have the required privilege to create feeds or real-time analytics. Your organization administrator can use the steps in Create roles and assign users to assign you to a portal role with the necessary privileges.

  • You can be in the administrative view working with your organization's content. On any feed or real-time analytic list pages, if you are an organization administrator, you can manage your content or the organization content. When you are managing your broader organization's content, you can inspect or stop any user's tasks, but you cannot create tasks on behalf of other users.

Common issues caused by JVM crash

Velocity uses a Java Virtual Machine (JVM) to run each of its core components — the Control Plane, Stream Server, Gateway, Metrics, Analytic Manager, and Feed Manager. Each component runs in its own dedicated JVM instance with configurable minimum and maximum memory thresholds that can be adjusted through the ArcGIS Administrative directory.

If feed or analytic logs indicate a JVM crash, consider the following causes:

Memory exhaustion (out of memory)

Memory exhaustion is one of the most common causes of a JVM crash. Each JVM instance is allocated a defined amount of memory. If a component's memory demand exceeds its configured maximum, the JVM runs out of heap space and crash.

Common triggers include:

  • High volume or velocity of incoming data overwhelming the Feed Manager or Stream Server

  • Too many concurrent analytics running

  • Memory thresholds set too low for the workload

Resource contention

If multiple JVM instances are competing for the same system resources, such as CPU or RAM, on an under-provisioned host, one or more components may become unstable and crash.

Misconfigured memory settings

If the minimum memory value is set higher than the host machine can provide, the JVM fails to start. If the maximum is set too low relative to the workload, the JVM crashes under load.

System restart

In the event of a planned or unplanned system restart, Velocity attempts to resume any feeds and real-time analytics that were in a started state before the restart. Feeds and analytics that were in a stopped, failed, or not yet run state are not automatically restarted.