--- title: Troubleshoot description: ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to help you set up and maintain your deployments. component: pinggateway version: 2023.11 page_id: pinggateway:maintenance-guide:troubleshooting canonical_url: https://docs.pingidentity.com/pinggateway/2026/maintenance-guide/troubleshooting.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-08-14T11:14:52Z keywords: ["Troubleshooting"] superseded_by: https://docs.pingidentity.com/pinggateway/2026/maintenance-guide/troubleshooting.html section_ids: getting-support: Getting support getting_info_about_the_problem: Getting info about the problem trouble-resource-display: Displaying resources troubleshoot-routes: Using routes troubleshoot-studio: Using Studio --- # Troubleshoot ForgeRock provides support services, professional services, training through ForgeRock University, 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 ForgeRock Identity Platform software. While many articles are visible to everyone, Ping Identity customers have access to much more, including advanced information for customers using ForgeRock 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 does not occur? * Is the problem permanent, intermittent, getting better, getting worse, or staying the same? If you contact ForgeRock for help, include the following information with your request: * The product version and build information. This information is included in the logs when IG starts up. If IG is running in development mode, and set up as described in the [Quick install](../getting-started/preface.html), access the information at http\://ig.example.com:8080/openig/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 ## Displaying resources > **Collapse: Requests redirected to AM instead of to the resource** > > By default, ForgeRock Access Management 5 and later 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 Access Management, requests can be redirected to Access Management instead of to the resource. > > To resolve this issue, add a cookie domain to the Access Management 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 IG in the documentation examples, the sample application must serve static resources, such as the .css. Add the following route to the IG configuration: > > ```json > { > "name" : "00-static-resources", > "baseURI" : "http://app.example.com:8081", > "condition": "${find(request.uri.path,'^/css') or matchesWithRegex(request.uri.path, '^/.*\\\\.ico$') or matchesWithRegex(request.uri.path, '^/.*\\\\.gif$')}", > "handler": "ReverseProxyHandler" > } > ``` > **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 does not have permission

" > } > } > ``` ## Using routes > **Collapse: No handler to dispatch to** > > * Symptom > > The following errors are in `route-system.log`: > > ```bash > ... | ERROR | main | o.f.o.h.r.RouterHandler | no handler to dispatch to > ``` > > ```bash > 08:22:54:974 | ERROR | http-... | o.f.o.h.DispatchHandler | no handler to dispatch to for URI 'http://ig.example.com/demo' > ``` > > * Cause > > IG 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. For examples, refer to [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, IG does not 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** > > IG 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, IG logs errors, but it keeps the previous, correct configuration, and continues to use the old route. > > IG only uses the new configuration after you save a valid version or when you restart IG. > > Of course, if you restart IG with an invalid route configuration, then IG 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** > > IG 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 IG from loading it. For example, rename a route as follows: > > ```bash > $ mv $HOME/.openig/config/routes/03-sql.json $HOME/.openig/config/routes/03-sql.inactive > ``` > > If necessary, restart IG to reload the configuration. When you have configured the environment, change the file extension back to `.json`. ## Using 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`. > > For information about creating routes in Studio, refer to the [Studio guide](../studio-guide/preface.html#preface). * Understanding timeout errors > **Collapse: Log is flushed with timeout exception warnings on sending a request** > > **Problem**: After a request is sent to IG, IG seems to hang. An HTTP 502 Bad Gateway error is produced, and the IG log is flushed with SocketTimeoutException warnings. > > **Possible cause**: The `baseURI` configuration is missing or causes the request to return to IG, so IG can't produce a response to the request. > > **Possible solution**: Configure the `baseURI` to use a different host and port to IG. - Other problems > **Collapse: Incorrect values in the flat files** > > Make sure the user running IG can read the flat file. Remember that values include spaces and tabs between the separator, so make sure the values are not padded with spaces. > **Collapse: Problem accessing URLs** > > The following error can be encountered when using an `AssignmentFilter` as described in [AssignmentFilter](../reference/Filters.html#AssignmentFilter) 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.