> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/maintain/upgrade/common-upgrade-errors/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Common upgrade errors

> Troubleshooting guide for errors commonly encountered when upgrading Itential Platform, including deprecated apps, admin group format issues, migration scripts, and RabbitMQ.

This guide covers errors you may encounter during a software upgrade, along with troubleshooting solutions.

## Deprecated app not loading

When loading Itential Platform you may see this error in the logs, indicating a deprecated method (`app-number`) is loaded but does not exist:

```
Error: ENOENT: no such file or directory, open '/opt/pronghorn/itential-bundle-5-20193_2019.3.6/node_modules/@itential/app-number/pronghorn.json'
    at Object.openSync (fs.js:443:3)
    at Object.readFileSync (fs.js:343:35)
    ...
```

### Solution

Remove the entry from the `service_configs` collection:

#### Find the service config document

Select the `service_configs` collection in your Itential Platform database. Search for the model shown in the error:

```bash
db.getCollection('service_configs').find({"model" : "@itential/app-number"})
```

![](/_fern-img/ce57a17e018f54dc2e3319152edbc0176bec746d509968fb7d2761197e62852a.webp)

#### Delete the document

Right-click the service config document and delete it.

![](/_fern-img/77f4b8510a80f5f8b4cdd2b7378e45e92a9b861062ba0c0b18e2ff5b7156a475.webp)

## Admin group not in proper format

When assigning roles to user groups, the UI does not correctly reflect selected roles as checked and an error box appears at the bottom of the screen.

![](/_fern-img/c62d5fddb04aa22d8431dab61ffb2e96dfcf17860a04496ce0ab21f2eabf85a3.webp)![](/_fern-img/276e3adf80fd430252d7c159d8ba86f2071a2ce10cb7b9c3d43c45805b71ff94.webp)

After running `journalctl -fu itential-platform`, the following error returns:

```bash
message=[ 'Error in web handler: TypeError: kg._id.equals is not a function' ]
```

### Solution

This issue is caused by the "admin" group having an `_id` that is a string rather than an ObjectID. Delete the group to fix it.

#### Back up the database

Back up the database using `mongodump`. Then use a GUI MongoDB client or the MongoDB shell to run the following commands:

```bash
mongo --host localhost --authenticationDatabase <authdb> -u admin -p <password> use pronghorn
```

```bash
db.groups.find({name: "admin"}).pretty()
```

A single document should return matching the admin user.

#### Remove the admin group

```bash
db.groups.remove({name: "admin"})
```

This should reflect 1 record removed.

#### Refresh the UI

Return to the Itential Platform UI and click **REFRESH** to fully reload the page. The "admin" group should no longer be present and groups should function normally.

## Jobs (Operations Manager) not showing updates

The Jobs UI is not showing any updates after running the upgrade.

### Solution

The migration scripts have not run. Change to the migration script directory and run the scripts:

```bash
cd <PRONGHORN_HOME>
cd ./current/node_modules/@itential/pronghorn-core/migration_scripts
node migratePropertiesToDatabase.js
```

## Devices not visible in Configuration Manager

The following error appears in `ConfigurationManager.log`:

```bash
No group access for [object Object] for action XXXX on entity of type device
```

![](/_fern-img/f2156a6a44bbca8b82c516bcb1fe8763373182c21dcd5b5c9f4e8dacc5dfd3df.webp)![](file:docs/assets/images/platform/18-configManagerUI\(1\).jpg)

### Solution

The migration scripts have not run. Change to the migration script directory and run the scripts:

```bash
cd <PRONGHORN_HOME>
cd ./current/node_modules/@itential/pronghorn-core/migration_scripts
node migratePropertiesToDatabase.js
```

## Failed to load schema warning

Beginning with the 2019.3 release, Itential Platform includes a built-in schema validation system for `pronghorn.json` inputs and outputs. This system identifies invalid schema formats and automatically converts them. In some cases the conversion script cannot handle the error, and a warning displays identifying the invalid data.

Valid types for `pronghorn.json` inputs and outputs:

```
['*', 'enum', 'object', 'string', 'array', 'boolean', 'integer', 'number']
```

* Type `'enum'` is not a valid JSON schema type — it will be set to `array`.
* Type `'*'` should only be used when you truly intend for an input/output to accept any type. Using this type limits JSON validation.
* Common invalid types include: `json`, `json[]`, `str`, `string[]`, and other variations.

**Example: Valid pronghorn.json**

```json
{
  "methods": [
    {
      "name": "getDevices",
      "summary": "Get the list of supported devices from Inventory for the siteId",
      "roles": ["admin"],
      "route": { "path": "/:siteId/devices", "verb": "GET" },
      "input": [
        {
          "name": "siteId",
          "type": "string",
          "description": "Site identifier to get equipment for",
          "required": "true",
          "in": "path",
          "schema": { "title": "devices", "type": "object" }
        }
      ],
      "output": {
        "name": "devices",
        "description": "success/failure response object",
        "type": "object",
        "schema": { "title": "devices", "type": "object" }
      },
      "task": true
    }
  ]
}
```

### Solution

Run the `fix-pronghorn_json.js` script to fix issues in `pronghorn.json`.

#### Download the script to your app folder

Download the script to your app folder:

```bash
app-folder_name
```

#### Execute the script

```bash
node fix-pronghorn_json.js pronghorn.json
```

#### Review the response

| Response                      | Message                                                  |
| ----------------------------- | -------------------------------------------------------- |
| Success                       | `pronghorn.json has been updated`                        |
| Success (no updates required) | `No methods detected in: pronghorn.json, file skipped`   |
| Failure                       | `pronghorn.json update cancelled due to previous errors` |

If a failure occurs, an error displays with a hint on how to fix it — typically invalid JSON or invalid types. Fix the issue and repeat step 2.

#### Push the updated file

If the update is successful, push `pronghorn.json` back to your repository.

#### Run migration scripts

```bash
cd <PRONGHORN_HOME>
cd ./current/node_modules/@itential/pronghorn-core/migration_scripts
node migratePropertiesToDatabase.js
```

## Task causing Workflow Engine to stall or crash

When an upgraded workflow is run, Workflow Engine either stalls or crashes at a specific task.

### Solution

Delete the task and recreate it.

## Error retrieving backups, device groups, and Golden Configurations

Errors occur in Configuration Manager when trying to retrieve backups, device groups, or Golden Configurations.

### Solution

#### Confirm MongoDB version

```bash
mongo --version
```

Confirm the version is 5.0.

#### Run the migration script

Navigate to the Configuration Manager migration scripts folder:

```bash
/node_modules/@itential/app-configuration_manager/migration_scripts
```

#### Execute the migration

For DEV/STAGING:

```bash
node migrate_to_jinja.js dev
```

For PROD:

```bash
node migrate_to_jinja.js
```

#### RestartItential Platform

```bash
sudo systemctl restart itential-platform
```

#### Verify

Try to retrieve backups, device groups, and Golden Configurations.

This applies toItential Platform 2022.1.x andItential Platform 2023.1.x only.

## RabbitMQ not starting

RabbitMQ will not start after being upgraded. Error messages similar to the following appear in the RabbitMQ log:

```bash
[error] <0.237.0> Feature flags: `classic_mirrored_queue_version`: required feature flag not enabled! It must be enabled before upgrading RabbitMQ.
[error] <0.237.0> Failed to initialize feature flags registry: {disabled_required_feature_flag,
[error] <0.237.0>                                               classic_mirrored_queue_version}
[error] <0.237.0> BOOT FAILED
```

### Solution

Enable the feature flag indicated in the error using `rabbitmqctl enable_feature_flag`. For example:

```bash
rabbitmqctl enable_feature_flag classic_mirrored_queue_version
```

For more information, see the [RabbitMQ feature flags documentation](https://www.rabbitmq.com/feature-flags.html).

> Troubleshooting guide for errors commonly encountered when upgrading Itential Platform, including deprecated apps, admin group format issues, migration scripts, and RabbitMQ.