--- title: Troubleshooting PingGateway issues description: Troubleshoot common PingGateway issues including startup failures, route errors, timeout problems, and Studio deployment issues component: pinggateway version: 2026 page_id: pinggateway:maintenance-guide:troubleshooting canonical_url: https://docs.pingidentity.com/pinggateway/2026/maintenance-guide/troubleshooting.html revdate: 2025-08-14T11:14:52Z keywords: ["Troubleshooting"] section_ids: getting-support: Getting support getting_info_about_the_problem: Getting info about the problem trouble-startup: Start up trouble-resource-display: Resources troubleshoot-routes: Routes troubleshoot-studio: Studio troubleshoot-downloads: Timeout errors other: Other problems --- # Troubleshooting PingGateway issues Ping Identity provides support services, professional services, training, and partner services to help you set up and maintain your deployments. ## Getting support Ping Identity provides support services, professional services, training, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see . Ping Identity has staff members around the globe who support our international customers and partners. For details on Ping Identity's support offering, visit . Ping Identity publishes comprehensive documentation online: * The Ping Identity [Knowledge Base](https://support.pingidentity.com/s/knowledge-base) offers a large and increasing number of up-to-date, practical articles that help you deploy and manage Ping Identity Platform software. While many articles are visible to everyone, Ping Identity customers have access to much more, including advanced information for customers using Ping Identity Platform software in a mission-critical capacity. * Ping Identity product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them. ## Getting info about the problem When trying to solve a problem, save time by asking the following questions: * How do you reproduce the problem? * What behavior do you expect, and what behavior do you have? * When did the problem start occurring? * Are their circumstances in which the problem doesn't occur? * Is the problem permanent, intermittent, getting better, getting worse, or staying the same? If you contact support for help, include the following information with your request: * The product version and build information. This information is included in the logs when PingGateway starts up. If PingGateway is running in development mode, and set up as described in the [Getting started with PingGateway](../getting-started/preface.html), access the information at http\://ig.example.com:8085/api/info. * Description of the problem, including when the problem occurs and its impact on your operation. * Steps you took to reproduce the problem. * Relevant access and error logs, stack traces, and core dumps. * Description of the environment, including the following information: * Machine type * Operating system and version * Web server or container and version * Java version * Patches or other software that might affect the problem ## Start up > **Collapse: After a first startup, PingGateway doesn't restart or load routes.** > > If PingGateway doesn't restart or load routes after a first startup, search `route-system.log` for lines containing `Error while starting…​` or `Unable to start …​` and use the error message to debug the issue. > **Collapse: PID file already exists** > > If PingGateway shuts down without using the `stop.sh` or `stop.bat` script, the PID file isn't removed and PingGateway can't restart. This can happen when you use the PingGateway service to stop or restart PingGateway, or when PingGateway is deployed in Docker. > > Remove the PID file or change the configuration as described in [Allow startup when there is an existing PID file](../installation-guide/start-stop.html#pidFileMode). ## Resources > **Collapse: Requests redirected to AM instead of to the resource** > > By default, AM writes cookies to the fully qualified domain name of the server; for example, `am.example.com`. Therefore, a host-based cookie, rather than a domain-based cookie, is set. > > Consequently, after authentication through PingAM, requests can be redirected to PingAM instead of to the resource. > > To resolve this issue, add a cookie domain to the PingAM configuration. For example, in the AM admin UI, go to Configure > Global Services > Platform, and add the domain `example.com`. > **Collapse: Sample application not displayed correctly** > > When the sample application is used with PingGateway in the documentation examples, the sample application must serve static resources, such as the .css. Add the following route to the PingGateway configuration: > > ```json > { > "name" : "00-static-resources", > "baseURI" : "https://app.example.com:8444", > "condition": "${find(request.uri.path,'^/css') or matchesWithRegex(request.uri.path, '^/.*\\\\.ico$') or matchesWithRegex(request.uri.path, '^/.*\\\\.gif$')}", > "handler": "ReverseProxyHandler" > } > ``` > > Source: [00-static-resources.json](../_attachments/config/routes/00-static-resources.json) > **Collapse: StaticResponseHandler results in a blank page** > > Define an entity for the response, as in the following example: > > ```json > { > "name": "AccessDeniedHandler", > "type": "StaticResponseHandler", > "config": { > "status": 403, > "headers": { > "Content-Type": [ "text/html; charset=UTF-8" ] > }, > "entity": "

User doesn't have permission

" > } > } > ``` ## Routes > **Collapse: No handler to dispatch to** > > * Symptom > > The following errors are in `route-system.log`: > > ```none > ... | ERROR | main | o.f.o.h.r.RouterHandler | no handler to dispatch to > ``` > > ```none > 08:22:54:974 | ERROR | http-... | o.f.o.h.DispatchHandler | no handler to dispatch to for URI 'http://ig.example.com/demo' > ``` > > * Cause > > PingGateway is not configured to handle the incoming request or the request to the specified URI: > > * "no handler to dispatch to": the router cannot find a route that accepts the incoming request. This error happens when none of the route conditions match the incoming request and there is no default route. > > * "no handler to dispatch to for URI": the router cannot find a route that can handle the request to the specified URI because none of the route conditions match the request path (URI). > > * Solution > > If the errors occur during the startup, they are safe to ignore. If the errors occur after the startup, do the following: > > * Identify why the request matched none of the [Route](../reference/Route.html) conditions, and adapt the conditions. You can find examples in [Example conditions and requests](../reference/Route.html#route-conditions). > > * Add a default handler to the [Router](../reference/Router.html). > > * [Add a default route](../getting-started/next-steps.html#add-default-route) for when no condition is met. > **Collapse: Object not found in heap** > > If you have the following error, you have specified `"handler": "Router2"` in `config.json` or in the route, but no handler configuration object named Router2 exists: > > ```none > org.forgerock.json.fluent.JsonValueException: /handler: > object Router2 not found in heap > at org.forgerock.openig.heap.HeapImpl.resolve(HeapImpl.java:351) > at org.forgerock.openig.heap.HeapImpl.resolve(HeapImpl.java:334) > at org.forgerock.openig.heap.HeapImpl.getHandler(HeapImpl.java:538) > ``` > > Make sure you have added an entry for the handler, and that you have correctly spelled its name. > **Collapse: Extra or missing character / invalid JSON** > > When the JSON for a route is not valid, PingGateway doesn't load the route. Instead, a description of the error appears in the log. > > Use a JSON editor or JSON validation tool such as [JSONLint](http://jsonlint.com/) to make sure your JSON is valid. > **Collapse: Route not used** > > PingGateway loads all configurations at startup, and, by default, periodically reloads changed route configurations. > > If you make changes to a route that result in an invalid configuration, PingGateway logs errors, but it keeps the previous, correct configuration, and continues to use the old route. > > PingGateway only uses the new configuration after you save a valid version or when you restart PingGateway. > > Of course, if you restart PingGateway with an invalid route configuration, then PingGateway tries to load the invalid route at startup and logs an error. In that case, if there is no default handler to accept any incoming request for the invalid route, then you have an error, `No handler to dispatch to`. > **Collapse: Skipped routes** > > PingGateway returns an exception if it loads a route for which it can't resolve a requirement. For example, when you load a route that uses an AmService object, the object must be available in the AM configuration. > > If you add routes to a configuration when the environment is not ready, rename the route to prevent PingGateway from loading it. For example, rename a route as follows: > > ```console > $ mv $HOME/.openig/config/routes/03-sql.json $HOME/.openig/config/routes/03-sql.inactive > ``` > > If necessary, restart PingGateway to reload the configuration. When you have configured the environment, change the file extension back to `.json`. ## Studio > **Collapse: Can't deploy routes in Studio** > > Studio deploys and undeploys routes through a main router named `_router`, which is the name of the main router in the default configuration. If you use a custom `config.json`, make sure it contains a main router named `_router`. > > You can find more information about creating routes in Studio in [PingGateway Studio](../studio-guide/preface.html). ## Timeout errors > **Collapse: Log is flushed with timeout exception warnings on sending a request** > > **Problem**: After a request is sent to PingGateway, PingGateway seems to hang. An HTTP 502 Bad Gateway error is produced, and the PingGateway log is flushed with SocketTimeoutException warnings. > > **Possible cause**: The `baseURI` configuration is missing or causes the request to return to PingGateway, so PingGateway can't produce a response to the request. > > **Possible solution**: Configure the `baseURI` to use a different host and port to PingGateway. ## Other problems > **Collapse: Incorrect values in the flat files** > > Make sure the user running PingGateway can read the flat file. Remember that values include spaces and tabs between the separator, so make sure the values aren't padded with spaces. > **Collapse: Problem accessing URLs** > > The following error can be encountered when using an `AssignmentFilter` as described in [AssignmentFilter](../reference/AssignmentFilter.html) and setting a string value for one of the headers. > > ```none > HTTP ERROR 500 > Problem accessing /myURL . Reason: > java.lang.String cannot be cast to java.util.List > Caused by: > java.lang.ClassCastException: java.lang.String cannot be cast to java.util.List > ``` > > All headers are stored in lists so the header must be addressed with a subscript. For example, rather than trying to set `request.headers['Location']` for a redirect in the response object, you should instead set `request.headers['Location'][0]`. A header without a subscript leads to the error above. > **Collapse: URI Too Long error** > > When a request is longer than 4096 bytes, it can cause an HTTP 414 URI Too Long response. > > The default limit for request length is set by the Vert.x configuration `DEFAULT_MAX_INITIAL_LINE_LENGTH`. This default acts on the `connectors` property of [admin.json](../reference/AdminHttpApplication.html). > > When working with requests constructed with parameters and query strings, such as for SAML or token transformation, where the request can become long consider setting the Vert.x property `getMaxInitialLineLength` to increase the limit. > > The following example configuration in `admin.json` increases the request length limit to 9999 bytes: > > ```json > "connectors": [ > { > "vertx": { > "maxInitialLineLength": 9999, > ... > } > } > ] > ``` > **Collapse: "Ignored" message logged** > > The following log message indicates that the client or server side has disconnected and PingGateway has ignored the event. > > ``` > [vert.x-eventloop-thread-2] DEBUG ... @system - Connection error. Ignored. > [CONTINUED]java.nio.channels.ClosedChannelException: null > ``` > > This type of error occurs when a network component closes the connection. This can occur when: > > * A load balancer or firewall terminates or times out connections > > * Third-party network changes prevent successful connections > > Increase logging to provide more information, as described in [Managing PingGateway logs](logging.html).