Unable to rename a field using ArcPy's AlterFields function in ArcGIS Pro

Description

When renaming a field using ArcPy’s AlterFields function in ArcGIS Pro, the following error message is returned even when the table is empty:

Error:   
arcgisscripting.ExecuteError: ERROR 001658: Cannot alter field types on populated tables. 
Failed to execute (AlterFields).

Cause

The Alter Fields tool used in the script interprets each field entry as a full field definition. When field type and field length parameters are not provided, the tool does not preserve the existing field type. As a result, the tool evaluates the operation as a field modification instead of a field rename, triggering an error because field types cannot be altered on populated tables.

Solution or Workaround

1. Open the project in ArcGIS Pro.
2. On the View tab, in the Windows group, click Python Window.
3. In the Python window, copy and paste the code below to rename the field in ArcGIS Pro.

Note:
Avoid pressing Enter between lines, as it creates indentation errors. The full script must be run at once.

1. Import the ArcPy library.

import arcpy

2. Replace <pathToFeatureClass> with the path to the feature class.

fc = r"<pathToFeatureClass>"

3. Define the mapping of original field names to new field names. Replace <OldName_1>, <OldName_2>, and <OldName_3> with the original field names, and <newName_1>, <newName_2>, and <newName_3> with the new field names.

field_map = {
    "<OldName_1>": "<newName_1>",
    "<OldName_2>": "<newName_2>",
    "<OldName_3>": "<newName_3>"
}

4. Initialize a list to store field definitions for use in the Alter Fields tool.

alter_list = []

5. Loop through all fields, set the new field names and properties, and execute the Alter Fields tool. Replace <OldName_1>, <OldName_2>, and <OldName_3> with the original field names, and replace <old_name> and <new_name> with the preferred variable names. Replace <FIELDTYPE> with the matching field types.

Note:
Ensure the field types and field length match the existing field definitions.

for <old_name>, <new_name> in field_map.items():
    
    if <old_name> == "<OldName_1>":
        alter_list.append([<old_name>, <new_name>, "", "<FIELDTYPE>"]) 
    
    elif <old_name> == "<OldName_2>":
        alter_list.append([<old_name>, <new_name>, "", "<FIELDTYPE>"])
    
    elif <old_name> == "<OldName_3>":
        alter_list.append([<old_name>, <new_name>, "", "<FIELDTYPE>"])

arcpy.management.AlterFields(fc, alter_list)

The code below shows the complete sample script.

import arcpy

fc = r"C:\Users\anan\Test_Projects\Project_TestAlter\Project_TestAlter.gdb\TestFC"

field_map = {
    "OldName_1": "newName_1",
    "OldName_2": "newName_2",
    "OldName_3": "newName_3"
}

alter_list = []

for old_name, new_name in field_map.items():
    
    if old_name == "OldName_1":
        alter_list.append([old_name, new_name, "", "TEXT", 255])
    
    elif old_name == "OldName_2":
        alter_list.append([old_name, new_name, "", "LONG"])
    
    elif old_name == "OldName_3":
        alter_list.append([old_name, new_name, "", "DOUBLE"])

arcpy.management.AlterFields(fc, alter_list)

4. Press Enter twice to execute the code.

The attribute table displays the updated field names.