How can I troubleshoot common errors when using the OEM_AGENT option with Amazon RDS Oracle?

Last updated: 2020-12-03

I have an Amazon Relational Database Service (Amazon RDS) DB instance that is running Oracle. I receive an error when I try to use the OEM_AGENT option with my DB instance. How can I troubleshoot and resolve common errors when using the OEM_AGENT option?

Short description

Amazon RDS supports the Oracle Enterprise Manager (OEM) Management Agent through use of the OEM_AGENT option. You might receive one of the errors described in this article when using the OEM_AGENT option with your Amazon RDS Oracle DB instance.

Note: Before proceeding with the troubleshooting steps, run the following pre-checks on your DB instance:

1. Check your DB instance's network configuration. The security group of your DB instance must allow OMS_HOST to listen to the OEM_AGENT port (default is 3872) and the RDS port (default is 1521).

2. Run a telnet test from the OMS server to your DB instance on the OEM agent port and database port to check connectivity.

3. Check your network configurations, including network access control lists (ACLs) and route tables. Verifying the configurations rules out the possibility of blockers or an explicit deny.

4. Make sure that the ports from your OMS server to the target DB instance are open.

    After you complete the above checks, check if OEM_AGENT upload is working. For more information on OEM_AGENT prerequisites, see Oracle Management Agent for Enterprise Manager Cloud Control.

    Follow the steps in this article, depending on the error or issue you are experiencing.


    Error: Unable to install the Oracle OEM_AGENT because the agent password is incorrect or expired

    Make sure that the agent password is correct and that it's not expired. On the OEM server, you can modify the existing agent registration password, or create a new password.

    Error: Unable to install the Oracle OEM_AGENT because the DB instance cannot reach the OMS host

    You receive this error when the OEM_AGENT fails to install because the OMS host/port can't be reached from the RDS host. To fix this, check if the OMS host can be reached from your DB instance.

    1. Launch an Amazon Elastic Compute Cloud (Amazon EC2) instance with the same network setup (SG/ACL) as your DB instance.

    2. Run a telnet command for the OMS host for port 4903:

    From EC2 instance: telnet OMS_HOST 4903

    3. Validate the connectivity by running a telnet test from the OMS server to your DB instance:

    From OMS host: telnet RDS-instance-endpoint 1521 (RDS default port)

    4. Check if the RDS host is able to resolve the OMS hostname into an IP address:

    SQL> SELECT UTL_INADDR.get_host_address('OMS_Host_Name') FROM dual;

    Error: You successfully installed the OEM_AGENT option on your DB instance. Your security group might not be configured correctly

    Even if your installation completes correctly, the RDS security group associated with your DB instance might be missing configurations to allow communication between the OMS host and DB instance.

    To resolve this error, verify that the agent port allows inbound traffic, and that your OMS host belongs to a security group that has access to the agent port. For more information, see Oracle Management Agent for Enterprise Manager Cloud Control.

    Error: Unable to install the Oracle OEM_AGENT because your OMS host version is not compatible with the agent version

    You receive this error if there is a compatibility issue between your OEM_AGENT version and the OMS host version. Currently, OEM_AGENT integrates with the OMS when both components run the same version. To resolve this error, choose compatible versions for both the OMS host and OEM agent.

    Error: Your OMS host is using an untrusted third-party certificate

    You received this error if you successfully install the OEM_AGENT option, but your OMS host is using a third-party certificate that isn't trusted. Configure your OMS host with the required trust certifications from your third party.

    Error: OEM_AGENT option is missing required option settings (Service: AmazonRDS; Status Code: 400; Error Code: InvalidParameterValue;

    You receive this error when OEM_AGENT is missing one of the required settings, and you need to update it. For more information on the required settings for OEM_AGENT, see Option settings for Management Agent.

    To resolve this error, review the settings in the OEM_AGENT option.

    1. Open the Amazon RDS Console.

    2. From the navigation page, choose Option configuration.

    3. From the Option settings section, find the OMS_HOST configuration. The Option settings panel shows only five resources by default, so you need to update your preferences to show all settings on one page.

    4. After you enter the required settings, add the OEM_AGENT option for your option group.

      Error: Heartbeat Status: OMS responded illegally [ERROR - Failed to Update Target]

      You receive this error when the OMS host is replaced after the OEM_AGENT option is attached to Amazon RDS.

      1. Clear the agent status, or re-start the OEM_AGENT using the steps in Performing database tasks with the Management Agent.

      2. Re-establish your connection with the OMS host.

      3. Check for compatibility issues with the OMS version and OEM_AGENT version. Run the following query to check if the table lists the OEM_AGENT version used in the option group:

      select type_meta_ver from sysman.mgmt_target_type_versions where target_type = 'oracle_emd';

      4. If the mgmt_target_type_versions output doesn't contain the OEM_AGENT version used in the option group, install the OEM_AGENT version that is listed in the command output.

      Error: Database instance doesn't show up in the targets in the OEM console

      You receive this error because the SSH to the underlying host is restricted on Amazon RDS. This is a prerequisite at the OS level for Auto Discovery to work correctly.

      Unlike the wizard-based Auto Discovery that's used when you add a target Oracle DB instance, you must manually add your Oracle DB instance as Target. This is required because of restrictions on the underlying host for Oracle DB instances.

      For more information on Agent limitations, see Oracle Management Agent for enterprise manager cloud control.

      Error: Unable to install the OEM_AGENT option because the agent port conflicts with the OMS port. Update the option settings and try again

      You receive this error because you have the wrong configuration for OEM_AGENT to work correctly. For example, you might have specified the same port number for both the OMS port and the OEM_AGENT port. To resolve this, change either the OMS port or the OEM_AGENT port number.

      Review the following Management Agent option settings:

      • AGENT_PORT - This port on the DB instance listens for the OMS host. The default is 3872. Your OMS host must belong to a security group that has access to this port.
      • OMS_PORT - This HTTPS port on the OMS Host listens for the Management Agent. To find the HTTPS upload port, connect to the OMS host and run this command:

      emctl status oms -details

      Error: Unable to install the Oracle OEM_AGENT because your DB instance does not have enough storage. Confirm that option group is supported on your DB instance class and configuration. If so, verify all option group settings and retry

      You receive this error when the provisioned storage for your DB instance doesn't have enough available storage as needed according to the OEM_AGENT prerequisites. For more information, see Prerequisites for management agent. Increase the storage space, and then re-install the OEM_AGENT option.