Troubleshooting

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to help you set up and maintain your deployments. For information about getting support, see Getting Support.

When you are 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 see?

  • 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. If IG is running in development mode, and set up as described in Getting Started Guide, access the information at http://openig.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

Troubleshooting
Displaying resources

By default, ForgeRock Access Management 5 and later writes cookies to the fully qualified domain name of the server; for example, openam.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 Access Management console, go to Configure > Global Services > Platform, and add the domain example.com.

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, as: 

$HOME/.openig/config/routes/static-resources.json
%appdata%\OpenIG\config\routes\static-resources.json
{
  "name" : "sampleapp_resources",
  "baseURI" : "http://app.example.com:8081",
  "condition": "${matches(request.uri.path,'^/css')}",
  "handler": "ReverseProxyHandler"
}

Define an entity for the response, as in the following example: 

{
  "name": "AccessDeniedHandler",
  "type": "StaticResponseHandler",
  "config": {
    "status": 403,
    "reason": "Forbidden",
    "headers": {
      "Content-Type": [ "text/html" ]
    },
    "entity": "<html><body><p>User does not have permission</p></body></html>"
  }
}
Using routes

If you get the message no handler to dispatch to, consider the following points:

  • Make sure that your routes include a condition configuration to match the request. For more information, see "Setting Route Conditions".

  • If requests might not match any condition, consider adding a default route to provide a default handler when no condition is met. For more information, see "Adding a Default Route". 

        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)

You have specified "handler": "Router2" in config.json or in the route, but no handler configuration object named Router2 exists. Make sure you have added an entry for the handler, and that you have correctly spelled its name.

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: 

        16:09:50 | ERROR | openig.example.com-startStop-1 | o.f.o.h.r.RouterHandler |
        The file '/Users/me/.openig/config/routes/zz-default.json' is not a valid route configuration.

Use a JSON editor or JSON validation tool such as JSONLint to make sure that your JSON is valid.

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 see an error, No handler to dispatch to.

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: 

$ 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

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 that it contains a main router named _router.

For information about creating routes in Studio, see the Studio User Guide.

Understanding timeout errors

(Not supported for IG in standalone mode.) If SocketTimeoutException errors occur in the logs when you try to download large files, in your ReverseProxyHandler or ClientHandler, increase soTimeout and set asyncBehavior to streaming.

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

Make sure that 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. 

        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

This error is typically encountered when using an AssignmentFilter as described in "AssignmentFilter" and setting a string value for one of the headers. 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.


Read a different version of :