Luca demonstrates how to
fix issues that cause the
"incompatible-parameters" state

rds-incompatible-parameters-luca

My Amazon RDS database instance is stuck in an incompatible-parameters state, and I cannot connect to the instance or make any modifications except for delete or reboot. How can I fix this?

When an RDS database instance is in the incompatible-parameters state, at least one of the parameters in the associated group is set with a value that is not compatible with the current engine version or instance class.

This may be caused by:

  • An instance that was scaled to use an instance type with less memory available than the previous one, and at least one of the memory settings in the associated parameter group exceeds the memory size available for the current instance.
  • A database engine that was upgraded to a different version, and is no longer compatible with one or more parameter settings of the current custom parameter group.

Attempts to associate a different parameter group, scale the instance type, change the engine version, or modify the instance configuration will fail. RDS instances must be in the available state in order to accept a new configuration. The only available options for an instance in incompatible-parameters state are Reboot and Delete. Check the associated custom parameter group setting in a pending-reboot state in order to recover from the incompatible state.

To resolve this issue, you must change the value of each incompatible parameter to a compatible value using one of the following options:

  • Reset all the parameters in the parameter group to the default value
  • Reset the values of the parameters that are incompatible

Note: All of the RDS instances associated with the incompatible parameter group will be affected by these value changes. If you want to back up the current parameter group settings, copy the parameter group before resetting it (optional).

A best practice to investigate the root cause of the issue is to make a copy of the incompatible parameter group. You can use the copied parameter group to compare the differences between custom parameter values and default values.

Using the RDS console

  1. Ensure you have selected the region that contains the RDS DB instance.
  2. Choose Parameter Groups.
  3. Choose the incompatible parameter group, and then choose Copy to create the copy of the parameter group.

Using the AWS Command Line Interface

You can use the AWS CLI to make a copy of the parameter group by using the copy-db-parameter-group command. To make a copy of an Aurora DB cluster parameter group, use the copy-db-cluster-parameter-group command.

The following sample code makes a copy of a custom parameter group:

aws rds copy-db-parameter-group --source-db-parameter-group-identifier INSERT-YOUR-SOURCE-PG-NAME-HERE --target-db-parameter-group-identifier INSERT-YOUR-TARGET-PG-NAME-HERE --target-db-parameter-group-description INSERT-A-DESCRIPTION --region INSERT-REGION-HERE

Using the AWS CLI

You can use the AWS CLI to make a copy of the parameter group by using the copy-db-parameter-group command. To make a copy of an Aurora DB cluster parameter group, use the copy-db-cluster-parameter-group command. Reset all parameters for the incompatible custom parameter group by using the reset-db-parameter-group or the reset-db-cluster-parameter-group command.

  1. Set parameter values for the parameter group to verify that the changes were applied by using the command describe-db-parameters for the database parameter group or the command describe-db-cluster-parameters for the cluster parameter group.
  2. Manually reboot the instance in order to apply changes by using the command reboot-db-instance with the --no-force-failover flag.

The following sample code illustrates the reset-db-parameter-group command:

aws rds reset-db-parameter-group --db-parameter-group-name INSERT-YOUR-PG-NAME-HERE --reset-all-parameters --region INSERT-REGION-HERE

The following sample code illustrates the describe-db-parameters command:

aws rds describe-db-parameters --db-parameter-group-name INSERT-YOUR-PG-NAME-HERE --region INSERT-REGION-HERE

The following sample code illustrates the reboot-db-instance command:

aws rds reboot-db-instance --db-instance-identifier INSERT-INSTANCE-IDENTIFIER-HERE --no-force-failover --region INSERT-REGION-HERE

Resetting the parameter values

If you want to avoid resetting all of the parameter values of the incompatible parameter group, you can choose which parameters to change. This can be done by editing the incompatible parameter group from the RDS console.

For information about how to determine which values are incompatible, see How do I identify which parameters are in custom parameter groups and which parameters are default?

Note: The RDS console allows you to change parameters to any related allowed values. The AWS CLI allows you to reset target parameters to their default values. Changes to parameter values using the AWS CLI to a value other than the default parameter value have no effect.

Using the RDS console

  1. Ensure you have selected the region that contains the RDS DB instance.
  2. Choose Parameter Groups.
  3. Choose the incompatible parameter groups.
  4. Choose Edit Parameters, enter the valid parameter values, and then choose Save Changes.
  5. Manually reboot the instance without fail-over to apply new settings.

Using the AWS Command Line Interface

Use the AWS CLI to apply changed values of parameters in a custom parameter group with the reset-db-parameter-group command with options --no-reset-all-parameters and --parameters to reset to the default value enlisted parameters. Reset an Aurora cluster parameter by using the reset-db-cluster-parameter-group command with the same options.

The --parameters option allows you to define parameter names, values, and specify a method for applying the parameter update. At least one parameter name, value, and apply method must be supplied; subsequent arguments are optional. A maximum of 20 parameters can be modified in a single request. The value to be set for the ParameterValue properties must be the default value defined for the parameter in the default parameter group of the related database engine version. Use the engine-default value to reset any modifiable parameter to the default engine value.

  1. Reset all parameters for the incompatible custom parameter group by using the reset-db-parameter-group or reset-db-cluster-parameter-group command using options --no-reset-all-parameters and --parameters.
  2. Set parameter values for the parameter group to verify that the changes were applied using the command describe-db-parameters.
  3. Manually reboot the instance to apply all changes using the command reboot-db-instance using the --no-force-failover flag.

The following sample code illustrates the command reset-db-parameter-group:

aws rds reset-db-parameter-group --db-parameter-group-name INSERT-YOUR-PG-NAME-HERE --region INSERT-REGION-HERE --no-reset-all-parameters --parameters 'ParameterName=INSERT-HERE-PARAMETER-NAME,ParameterValue=engine-default,ApplyMethod=INSERT-HERE-A-SUPPORTED-APPLY-METHOD'

The following sample code illustrates the describe-db-parameters command:

aws rds describe-db-parameters --db-parameter-group-name INSERT-YOUR-PG-NAME-HERE --region INSERT-REGION-HERE

The following sample code illustrates the reboot-db-instance command:

aws rds reboot-db-instance --db-instance-identifier INSERT-INSTANCE-IDENTIFIER-HERE --no-force-failover --region INSERT-REGION-HERE


Did this page help you? Yes | No

Back to the AWS Support Knowledge Center

Need help? Visit the AWS Support Center

Published: 2016-11-11