Troubleshoot administration

 

+
Search Tips   |   Advanced Search

 

 

Troubleshoot issues related to using or administering the portal

This section describes problem that can occur when using or administering the portal.

 

No pages display in the portal (UNIX installations with IBM DB2 Universal Database Enterprise Server Edition )

If you selected the option to deploy the base portlets...

  • administration
  • customization portlets

...during the portal installation, but no pages are displayed when you open the portal and the following error messages are in the installation log...

com.ibm.wps.util.DataBackendException: Error during database access!

Nested Exception is com.ibm.websphere.ce.cm.StaleConnectionException:

[IBM ][CLI Driver] SQL1224N A database agent could not be started to service a request, or was terminated as a result of a database system shutdown or a force command.

SQLSTATE=55032

...there is a shared memory problem with DB2 and the WebSphere Application Server datasources.

Solution:

On UNIX installations, do not use the WebSphere Portal database directly. Instead, define a local alias for the database. The alias connects to the database using TCP/IP.

To set up a local alias, see instructions for configuring DB2.

 

Browser switches to another session when multiple users are logged in from the same client

If a user...

  1. Logs in to the portal
  2. Leaves that login active, and then logs in from another instance of the same browser using a different user ID

...the second instance of the browser might switch to the first user's session and other problems might occur.

Solution:

If we need to log in as different users on the same client, to avoid this problem...

  • If you do not need to maintain session data for any of the user logins, log off from one user account before logging in to the other user account.

  • If we need to maintain active sessions for each user, use a different browser type for each user session. For example, use Netscape Navigator for one login and Microsoft Internet Explorer for the second login.

 

When modifying user information via WebSphere Portal, unexpected results could occur

When modifying user information via WebSphere Portal, if you receive the error...

Backend storage system failed. Please try again later

...or the user attributes are not updated in LDAP, it might mean that the default tuning parameters for use with DB2 and IBM Tivoli Directory Server need to be adjusted.

Solution:

The default DB2 parameters are:

APP_CTL_HEAP_SZ 128
APPLHEAP_SZ 128

The parameters above are too small for Tivoli Directory Server and WebSphere Portal on AIX with 2000 user entries.

The HEAP size of UDB is required when updating or inserting data. WebSphere Portal spawns heavy transactions to the LDAP server in any phase, especially changing user attributes, which spawns several updates and inserts. To prevent this problem, the following WebSphere Portal tuning is required:

su -ldapdb2
db2 -c update db cfg for ldap using APP_CTL_HEAP_SZ 1024
db2 -c update db cfg for ldap using APPLHEAP_SZ 1024

 

Application error for Edit Layout and Content

An application error might occur when you use the Edit Page task. The sequence of events that result in the problem are:

  1. A new user signs up or enrolls for the portal.

  2. The user logs in.

  3. The user selects the page to work with.

  4. The user selects the Edit Page.

  5. The user selects a portlet on the page and then clicks the edit portlet icon. The edit portlet dialog is displayed in a separate window.

  6. The user edits the portlet and then clicks the OK button. The edit portlet window closes.

  7. The user clicks the edit portlet icon a second time. This time, the edit portlet dialog displays in a separate window, but with the message There has been an application error.

Solution:

If this problem occurs, the user should log off and then log in again. Then the problem will not occur again.

 

A portlet does not appear in the portal

Solution:

Ensure that:

  • You are authorized to access the portlet.

  • The portlet has been added to a page in the portal.

  • You are viewing the page that contains the portlet.

  • The device on which you are viewing the portal supports the markup language that the portlet produces.

 

Portlet contents are blank

When a portlet Web application is unavailable, for example because it was stopped in the application server, the corresponding portlets will not show an error message but just display no content. In this case, the log file will show one of the following error messages:

  • PEPC0001E: ServletContext belonging to servlet XX could not be found.

  • PEPC0003E: ServletContext lookup for XX returned the portal's context. It has to be a different one.

Solution:

Make sure the enterprise application is started by using the application server's administrative console.

 

A portlet is not accessible after its portlet application has been updated

Solution:

When a portlet application is updated, the updated portlet or portlets might be temporarily inaccessible. If this happens, log out and log back in to the portal again.

 

An error message after an LTPA timeout that follows a session timeout

After an LTPA timeout following a session timeout, an IllegalArgException error might be displayed and a new login is required.

Solution:

Refresh the Web browser by doing one of the following:

  • For Netscape users, press and hold the Shift key and click Reload

  • For Internet Explorer users, press and hold the Shift key and click Refresh.

 

User or user group search can time out or return too many results

When performing a search that can return a large number of users or user groups, the search might time out or return more results than the system can handle.

Solution:

Change maximum search results or time out

 

Browser refresh forces a portlet transaction

For portlets that use String-based actions, refreshing the browser could cause the portlet to re-execute its action, creating a problem in some transactional portlets. For example, a user clicking refresh could inadvertently trigger an action that updates the quantity of an item in a shopping cart.

Solution:

Modify the portlet by going to...

Administration | Portlets | Manage Portlets | portlet | Modify

...and setting...

com.ibm.wps.portlet.action.redirect = true

This allows the page and portlet to be reloaded without the action parameters in the URL.

 

Receiving session timeout screen

When a user from another application server instance within the single signon domain of WebSphere Portal with a Session cookie that has the name JSESSIONID and a cookie path that...

  • Matches the portal URL (for example, /)
  • Accesses the WebSphere Portal protected area (for example, myportal)

...the user will see the session timeout screen. This is because WebSphere Portal cannot distinguish if the cookie sent by the browser was created by itself or by another application server instance.

Solution:

To prevent this problem, the cookie path has to be adjusted so that it can be distinguished from the WebSphere Portal URL in the other Application Server instances that share the same single signon domain. Use the Session Management settings in IBM WAS Administration to specify a unique cookie path for the JSESSIONID cookie.

If specify cookie path using "overwrite" option in the session management administration screen at a level other then the web container level, you will have to again specify distributed session settings at that level even though they might already be defined at the web container level.

 

Logging in as two users with a Mozilla browser continues to show one user

Mozilla browsers that come from the same IP address share a common WebSphere Portal session. If a user logs in with two different user IDs at the same time, the browser continues to use the same user, and there is no indication which user is actually logged in to WebSphere Portal. For example, if a user logs in as UserA in one browser window and UserB in another browser window, both windows are UserB, and all content and settings displayed belong to UserB.

Solution:

To login as a different user with a Mozilla browser, close all browser instances before logging in as the alternate user.

 

Parallel portlet rendering does not work when Work Manager is not found

If a Work Manager is not created during the portal installation, the portal gives the following message:

PEEX0100E Unable to find workload manager wm/wpsWorkmanager

This error message indicates that the Work Manager was not created during portal installation. This can have the following reasons:

  • Programming Model Extensions (PME) was not installed.
  • The asynchronous beans were not selected for the PME installation.

As a result, parallel portlet rendering (PPR) does not work.

When this error occurs, parallel portlet rendering is automatically turned off. The Portal continues to operate properly and all portlets are rendered sequentially.

Solution:

Verify the following prerequisites have been installed...

  1. The application server is installed including PME.

  2. PME includes the asynchronous beans required to create a Work Manager.

  3. A Work Manager named...

    wm/wpsWorkmanager

    ...was created during the portal installation.

 

Portal URLs need authentication for anonymous users

The new URL Function creates Portal URLs with the protected URI, which by default is /myportal. This forces a need for authentication even if the anonymous user is granted access to the label, page and New URL.

Scenario: A user creates a new label, Label A, under the context root of Portal (same level as the "Home" label). An administrator then creates a page under Label A, for example, Page A. The administrator then adds portlets to Page A. At this point the page is still not visible to an anonymous user because its URL must be created so that its link displays Label A and Page A. To create the proper URL the administrator now accesses...

Administration | Manage Pages | Home | New URL

The new URL that is created is a link to Label A. In this example, the radio button...

A link to the following Portal page

...is selected. The anonymous user is now added to the user role of the new URL that was created. This will now allow the anonymous user to be able to view a link to Label A. However, when the link is selected the portal server will still prompt the user to enter valid credentials.

Cause: The user is prompted to enter valid credentials because the "New URL" button creates all links in the form...

/wps/myportal/foo/bar

By default, the /myportal URL is protected, which means that a user must authenticate to be able to view the contents.

Solution:

Create a URL for Label A and Page A using URL Mapping

Then, instead of selecting...

A link to the following Portal page

...select...

A link to a webpage with the following URL

Now when creating a New URL, we can use the external link of...

http://hostname/wps/portal/TestLink

...in order to avoid the authentication requirement by avoiding the /myportal URL.

 

Document Search portlet fails on anonymous page

If you put the Document Search portlet on an anonymous page so that users can use it without having to log in to the portal, the portlet does not work.

Solution:

You need to enable public sessions for the portal. The reason is that the document search portlet needs a valid session for its run time, and by default, sessions are not enabled on anonymous pages in the portal. By default, sessions are only created when a user authenticates and logs in to the portal server.

To enable public sessions, edit the NavigatorService.properties file that is located in the WebSphere Portal installation directory:

Set the public.session parameter to true. Restart both WAS and WebSphere Portal for the changes to take effect.

 

Search portlets do not work after reconfiguring from local to remote service or vice versa

If you change the configuration of the search related portlets from local search service to remote search service or vice versa, the portlet does not work. This applies to both the administrative portlet Manage Collections and the end user portlet Document Search.

Cause: We can configure and use the embedded search component in two ways....

  1. Accessing a locally installed search service
  2. Using a remote search service through the Web services (SOAP) interface.

Once you have configured one of the search portlets for access local search service or remote search service, we cannot change its configuration to the other type of service. If you try to do this, the portlet does not work any more.

Solution:

To switch to the other type of service. for example, from local to remote, create another copy of the portlet and configure it for the required service type. To configure for local access, leave the SOAP URL parameter empty and to configure for remote access, specify a SOAP URL.

 

Cannot use the XML configuration interface if it is externalized in security

If the virtual resource XML_ACCESS that represents access to the XML configuration interface is put under protection of an external security manager, we can no longer use the XML configuration interface.

Solution:

If the access rights of WebSphere Portal are externalized to an external security manager, such as IBM Tivoli Access Manager for e-business, verify the XML configuration interface virtual resource is not externalized.

 

Link to launch Edit mode of a portlet disappears

When you use the Edit Layout portlet to edit a page, the page is deactivated and the link to launch the Edit mode of a portlet on that page disappears.

Cause: A page is deactivated immediately after you perform an action in the Edit Content and Layout portlet, for example, Add Portlets or Move Portlets/container.

Solution:

Once the page is deactivated after you an action, we need to click Done to leave the page. This activates the page again. When you click the Edit Page link, the Edit Portlet link is displayed.

 

Administrative Console not loading

WebSphere Portal installs the WAS Administrative Console application into the WebSphere Portal application server so that it can be used to administer the application server without requiring another application server instance (by default, server1) to be configured or operational. The default port used for communication is 10038.

Solution:

On Windows 2000, a Start Menu item is created to invoke the Administrative Console. If this menu item fails to load the console because of a HTTP 404 error that means that the Application Server is assigned a different administration port than was configured in the shortcut for this Start Menu item.

You might have to change the property of WAS Administrative Console in Windows 2000 Start Menu

Start | Programs | IBM WebSphere | Application Server | Administrative Console

For example, change...

C:\Program Files\Internet Explorer\IEXPLORE.EXE http://<hostname>:9060/admin/

...to...

C:\Program Files\Internet Explorer\IEXPLORE.EXE http://<hostname>:10038/admin/

 

Portlet deployment fails due to transfer or timeout problems

Deploying a portlet application by using the Web Modules portlet might fail due to transfer or timeout problems, with the portlet returning to the initial state.

Scenario detail: When you deploy a portlet application Web module by clicking the Install button in the Web Modules portlet, selecting a Web module from the browse dialog and clicking Next, the portlet might return to the initial state as it was before you clicked the Install button. No error message is displayed.

In wps_timestamp.log, you might see...

Nested Exception is org.apache.jetspeed.portlet.PortletException: Processing of multipart/form-data request failed. Read timed out.

Cause: A timeout might have occurred on the HTTP connection when trying to install the portlet application WAR file. This problem can depend on several factors, for example:

  • The size of the WAR file that you want to install.

  • The bandwidth and load on the network.

  • The timeout limits for several processes, for example the post size limit, the connection input and output, the upload process, or the SOAP connection.

Solution:

To resolve this problem, try changing one or more of the properties or timeout values that can affect the installation of the WAR file. Here are some examples:

  • Increase the property PostSizeLimit in the plugin-cfg.xml property file of the HTTP server.

  • Set the property ConnectionIOTimeout.

    This property does not exist by default in the WAS configuration. To set...

    1. Increase the value of ConnectionIOTimeOut for the WebSphere_Portal and ND dmgr (server1) application servers. For the WebSphere_Portal appserver, log into the administrative console for the portal node, and go to...

      Servers | Application Servers | WebSphere_Portal | Web container settings | Web container transport chains

    2. For each entry listed in the Web container transport chains section, click HTTP Inbound Channel, and set...

      Read timeout 180
      Write timeout 180

Use discretion when changing these values. Depending on the portal configuration and the size of the WAR file to be installed, it might be sufficient to increase one parameter, or you might have to increase more than one parameter. You might have to set one or more parameters to infinite.

 

Extracting a JNDI namespace in WebSphere Portal

WAS provides a command line utility...

app_server_root/bin/dumpNameSpace.sh

...for creating a JNDI namespace extract of a dedicated application server.

To extract a namespace from a server...

  • The application server must be active.

  • The target host name must be provided, if it is not extracted locally.

  • The target port number must be provided, if it deviates from the default.

For a detailed list of parameters for the dumpNameSpace utility...

cd app_server_root/bin
dumpNameSpace.sh ?

The default connection port is 2809. To determine the port number. go to...

Servers | Application Servers | Ports | BOOTSTRAP_ADDRESS

To extract the JNDI namespace...

cd app_server_root/bin
dumpNameSpace.sh/bat -port port

...where port is the port number that you looked up in the Administrative Console.

The result is written to the standard output.

 

WebSphere Portal hangs on Windows with JVM Heap Size larger than 1430 MB

You might experience a Portal System Hang on Windows if the JVM Heap Size is set at larger than 1430 MB.

Solution:

Set the heap size to less or equal than 1430 MB. See page 12 of the performance tuning guide for reference.

 

Error occurs when exporting files from various portlets

You may receive one of the error messages below if using Internet Explorer:

Manage Pages <failure>com.ibm.wps.command.MissingParameterException: EJPEB0612E: AbstractXmlExtractCommand Missing Parameter.</failure>
Template Library Error message in browser information bar
Policy XML document must have a top level element. Error processing resource

Solution:

Open Internet Explorer and click...

Tools | Internet Options | Security tab | Custom Level button | Downloads | Automatic prompting for file downloads | Enable

 

Exporting portal resources by using the administrative user interface does not work

You export a portal resource by using the portal administrative interface, but the export is not completed properly. For example, this can happen when exporting a page from the Manages Pages Portlet.

Cause: The export can be restricted by the security settings of the browser. For example, when you export a page, portal performs the XML export into an XML script file, but restrictive browser security settings can prevent the file from being saved.

Solution:

Configure the security settings of the browser so that they allow the export of portal resources. We can configure these settings to suit the requirements. For example, we can set up the browser so that it prompts us to confirm saving of the file.

 

Error message EJPPH0004E on renamed wps.ear file

Portal shows the following message...

EJPPH0004E: Administration rights for Application Server are missing.

Cause: The portal EAR file wps.ear has been renamed.

Solution:

Change the name of the file back to wps.ear. Do not rename the file. In the administration console the portal must be shown as an enterprise application with the name wps.ear.

 

Troubleshoot issues related to national language support

This section describes problems that can occur when viewing different languages with WebSphere Portal.

 

Issues with Netscape AIX set to Turkish

If you access the portal using a Netscape browser running on an AIX client where the locale and the key layout are set to Turkish, some Turkish characters might not display correctly and log in might fail because Netscape on AIX is provided on a limited warranty basis.

Solution:

If problems are encountered, IBM recommends that an alternate browser or a browser on a different operating system be used to connect to the portal.

 

Issues with browsers displaying DBCS characters in selection boxes

This information concerns languages that use double-byte character sets (DBCS). Sometimes when DBCS text is displayed in selection boxes (such as the selector for pages), all of the characters are displayed as square boxes. It has not been possible to determine the browser versions and operating systems on which this situation occurs consistently.

Solution:

None at this time.

 

Issues with information center and Portal Help search

If you use Microsoft Internet Explorer 6.x to display the WebSphere Portal information center or Portal Help and then use the Search function, some corrupted characters might be displayed in the search results list.

Solution:

See the Requirements section in the information center to view a list of other Web browsers that we can use.

 

Issues with Microsoft Internet Explorer in a Japanese environment

Solution:

  • If you access the portal in a Japanese environment with Microsoft Internet Explorer, the backslash might be displayed when pushing the Japanese Yen key in an input field of the portal. This is caused by Microsoft Internet Explorer in UTF-8 encoding. To avoid this problem, use other browsers such as Netscape or Mozilla, or change the character set of the portal from UTF-8 to Shift_JIS. Refer to Change the character set for a language.

  • The Rich Text Component of WebSphere Portal Productivity Components allows us to change a normal format to a heading format, and vice versa. This might be not available if you access the portal in a Japanese environment with Microsoft Internet Explorer. To avoid this problem, use other browsers such as Mozilla.

 

Search Crawler OutofMemory error

You might receive an OutofMemory error when using Search Crawler on large portlet JSPs.

Solution:

Either pre-compile the large portlet before using Search Crawler or increate the the JVM max heap size.