Internal server error when using User Self-Service in AM 5 and 5.1

Last updated Jan 5, 2021

The purpose of this article is to provide assistance if a user gets an "Internal server error" when using the User Self-Service in AM 5 and 5.1, for example, they click the Forgotten Password? link on the login page. You will also see an "ERROR: Unable to handle read" message in the logs.

1 reader recommends this article


The following message is shown when using the User Self-Service:

Internal server error

An error similar to the following is shown in the org.forgerock.openam.selfservice.SelfServiceRequestHandler debug log:

org.forgerock.openam.selfservice.SelfServiceRequestHandler:04/18/2017 02:11:39:934 PM BST: Thread[http-bio-8080-exec-10,5,main]: TransactionId[86089244-87fc-458f-8b1d-d2e1d6668aec-241] ERROR: Unable to handle read java.lang.IllegalArgumentException: Required attribute selfServiceForgottenPasswordEmailBody at at at org.forgerock.openam.selfservice.SelfServiceRequestHandler.createNewService( at org.forgerock.openam.selfservice.SelfServiceRequestHandler.getService( at org.forgerock.openam.selfservice.SelfServiceRequestHandler.handleRead( at org.forgerock.json.resource.Router.handleRead( at org.forgerock.json.resource.FilterChain$Cursor.handleRead(

The required attribute specified in the log may vary. For example, "Required attribute selfServiceEncryptionKeyPairAlias" has also been seen.

Recent Changes

Upgraded to, or installed AM 5 or 5.1.

Configured User Self-Service as a Global Service (navigate to: Configure > Global Services > User Self-Service).


There is a known issue: OPENAM-11057 (Global User Self Service UI does not display values), where the global User Self-Service UI does not display the default values that are returned by the server. When you configure User Self-Service at a global level, only the settings you specify are saved and any default values are removed upon Save.


This issue can be resolved by upgrading to AM 5.1.1 or later; you can download this from BackStage.


This issue can be resolved by configuring all the necessary values using ssoadm or the console:

ssoadm: The following process steps through checking what settings have been saved and then adding new values via ssoadm:

  1. Check what settings have actually been set using the ssoadm get-attr-defs command, for example: $ ./ssoadm get-attr-defs -s selfService -t organization -u amadmin -f pwd.txt selfServiceProfileProtectedUserAttributes= selfServiceValidQueryAttributes=uid selfServiceValidQueryAttributes=mail selfServiceValidQueryAttributes=sn selfServiceValidQueryAttributes=givenName selfServiceForgottenUsernameCaptchaEnabled=false selfServiceForgottenPasswordServiceConfigClass=org.forgerock.openam.selfservice.config.flows.ForgottenPasswordConfigProvider selfServiceSigningSecretKeyAlias= selfServiceForgottenUsernameEmailUsernameEnabled=true selfServiceForgottenPasswordConfirmationUrl=${realm}#passwordReset/ selfServiceUserRegistrationCaptchaEnabled=false selfServiceUserRegistrationServiceConfigClass=org.forgerock.openam.selfservice.config.flows.UserRegistrationConfigProvider selfServiceForgottenUsernameShowUsernameEnabled=false selfServiceMinimumAnswersToVerify=1 selfServiceForgottenPasswordEnabled=false KeyAliasValidator=org.forgerock.openam.selfservice.config.KeyAliasValidator selfServiceCaptchaSiteKey= selfServiceCaptchaSecretKey= selfServiceUserRegistrationEnabled=false selfServiceUserRegistrationDestination=default selfServiceUserRegistrationValidUserAttributes=inetUserStatus selfServiceUserRegistrationValidUserAttributes=mail selfServiceUserRegistrationValidUserAttributes=username selfServiceUserRegistrationValidUserAttributes=sn selfServiceUserRegistrationValidUserAttributes=userPassword selfServiceUserRegistrationValidUserAttributes=kbaInfo selfServiceUserRegistrationValidUserAttributes=givenName selfServiceMinimumAnswersToDefine=1 selfServiceForgottenUsernameKbaEnabled=false selfServiceForgottenUsernameEmailBody=en|<h2>Your username is <span style="color:blue">%username%</span>.</h2> selfServiceForgottenPasswordEmailVerificationEnabled=true selfServiceForgottenUsernameTokenTTL=900 selfServiceUserRegistrationTokenTTL=900 selfServiceUserRegistrationKbaEnabled=false selfServiceEncryptionKeyPairAlias= selfServiceUserRegistrationEmailBody=en|<h2>Click on this <a href="%link%">link</a> to register.</h2> selfServiceUserRegistrationEmailSubject=en|Registration email selfServiceUserRegistrationEmailVerificationEnabled=true selfServiceForgottenUsernameServiceConfigClass=org.forgerock.openam.selfservice.config.flows.ForgottenUsernameConfigProvider selfServiceForgottenUsernameEnabled=false selfServiceForgottenUsernameEmailSubject=en|Forgotten username email selfServiceCaptchaVerificationUrl= selfServiceForgottenPasswordTokenTTL=900 selfServiceForgottenPasswordEmailSubject=en|Forgotten password email selfServiceUserRegistrationConfirmationUrl=${realm}#register/ selfServiceForgottenPasswordCaptchaEnabled=false selfServiceForgottenPasswordKbaEnabled=false selfServiceKBAQuestions=4|en|What is your mother's maiden name? selfServiceKBAQuestions=2|en|What was the model of your first car? selfServiceKBAQuestions=1|en|What is the name of your favourite restaurant? selfServiceKBAQuestions=3|en|What was the name of your childhood pet? Schema attribute defaults were returned.
  2. Add any missing attributes, using the ssoadm set-attr-defs command. For example, to set the selfServiceForgottenPasswordEmailBody attribute noted in the log: $ ./ssoadm set-attr-defs -s selfService -t organization -u amadmin -f pwd.txt -a selfServiceForgottenPasswordEmailBody="en|<h2>Click on this <a href="%link%">link</a> to reset your password.</h2>" You can set multiple attributes using ssoadm as detailed in How do I add multiple attributes with a single ssoadm command in AM/OpenAM (All versions)?

You must add the attributes as shown in the log / get-attr-defs output, that is, they must have the selfService prefix. There is a known issue with the documentation whereby they are shown without this prefix: OPENAM-11046 (ssoadm properties in Self-Service docs are missing selfService prefix).    

Console: Navigate to: Configure > Global Services > User Self-Service and complete all the required fields on the General Configuration tab and the tab specific to the functionality you are configuring. (You can also do this at the realm level by navigating to: Realms > [Realm Name] > Services and adding the User Self-Service.)

For example, the following screenshots display the default settings needed to configure the Forgotten Password functionality for all realms (the General Configuration tab must be completed for all areas of User Self-Service):

  • General Configuration tab:

  • Forgotten Password tab:

See Also

User Self Service Guide

Related Training


Related Issue Tracker IDs

OPENAM-11057 (Global User Self Service UI does not display values)

OPENAM-11046 (ssoadm properties in Self-Service docs are missing selfService prefix)

Copyright and TrademarksCopyright © 2021 ForgeRock, all rights reserved.