Why does Ignition 8.3 fail to start after an 8.1 upgrade?

An Ignition gateway upgraded from 8.1 installs cleanly, then aborts during context startup because one migrated identity provider (IdP) resource carries "settings": null. The IdP was created in an older 8.1 release that pointed at its user source by numeric ID. That user source no longer exists, so the migration writes an IdP with no settings. The 8.3 validator then throws a NullPointerException when it calls authMethods() on that null object. Inductive Automation tracks the defect as IGN-13838. One reported occurrence was an upgrade from 8.1.51 to 8.3.2.

Where in the startup sequence does the gateway stop?

Read the stack trace bottom-up, the way the request actually travels. The service wrapper launches the JVM. The JVM starts the gateway context. The context starts redundancy, then the identity provider manager, which loads every IdP resource from disk and validates it. The failure happens at the last hop:

The exception is not contained at the IdP level. It propagates up to the context startup, which logs Error during context startup and leaves the gateway down. A single bad IdP file therefore takes the whole gateway offline, including the web interface.

Check: Open wrapper.log in the installation's logs directory. Search for Error during context startup. Confirm the next line reads:

java.lang.NullPointerException: Cannot invoke "com.inductiveautomation.ignition.gateway.auth.idp.internal.InternalIdentityProviderConfig.authMethods()" because "settings" is null

If the top frame is a different class, you have a different startup failure. Skip to the section on persistent failures and follow that decision path.

Why does the installer report success when the gateway cannot start?

The installer only replaces binaries. It does not convert your configuration. The 8.1 configuration is migrated into 8.3's file-based resources under data\config\resources when the gateway boots. During that migration, IdentityProviderMigrationStrategy resolves each IdP's user source reference.

Older 8.1 IdPs stored the user source as a numeric profile ID. Current builds store it by name. If that ID no longer maps to a user source, the migration logs a warning and writes the IdP with settings set to null. The resource is left on disk. Every later startup then reads it and fails at hop 6.

The warning and the fatal error are separated in time. In the captured log, the warning appeared at 13:48:22 and the context startup error at 13:59:51. If you only read the tail of the log, you will miss the cause.

Check: Search wrapper.log for IdentityProviderMigrationStrategy. Record every user source ID it reports as missing. Each one is a separate broken IdP.

How do you clear the orphaned reference before upgrading?

This path avoids the failure entirely. Use it if the gateway is still on 8.1, or if you restore 8.1 to retry the upgrade.

1. Take a gateway backup (.gwbk) of the running 8.1 gateway.
2. List the user sources that exist on the gateway.
3. Open the Identity Providers page in the gateway's security configuration. Check which user source each internal IdP authenticates against.
4. Handle any IdP that points at a user source that is not in the list from step 2. Either delete it, or recreate it against a user source that exists. An IdP created in the current build references its user source by name.
5. If the removed IdP was bound to gateway security or to project security, rebind those items to a working IdP.
6. Take a second .gwbk, then run the upgrade.

Check: On first 8.3 boot, wrapper.log contains no User source profile with ID ... does not exist lines. It also contains no Error during context startup.

How do you repair the identity-provider config.json on an upgraded gateway?

If the gateway is already on 8.3 and down, fix the resource file directly.

1. Stop the Ignition service.
2. Copy the data\config directory to a safe location so you can revert.
3. Navigate to <install dir>\data\config\resources\core\ignition\identity-provider. Each IdP has its own subfolder containing a config.json.
4. Find every config.json that contains "settings": null. Use the search command below.
5. For each one, choose a fix:
   • Delete the IdP's folder if nothing on the gateway uses that IdP.
   • Replace the null with a valid settings object if gateway security or a project depends on the IdP.
6. Set userSource to the name of a user source that exists on this gateway. default works only if a user source with that name exists.
7. Save the file as valid JSON with no trailing commas, then start the service.

Replacement settings block:

"settings": {
  "authMethods": [
    {
      "config": {},
      "type": "basic"
    }
  ],
  "rememberMeExp": 0,
  "sessionExp": 0,
  "sessionInactivityTimeout": 30,
  "userSource": "default"
}

Check: Before starting the service, confirm no null settings remain and each edited file parses:

Get-ChildItem "<install dir>\data\config\resources\core\ignition\identity-provider" -Recurse -Filter config.json |
  Select-String -Pattern '"settings"\s*:\s*null'

Get-Content "<path to edited>\config.json" -Raw | ConvertFrom-Json

The first command must return nothing. The second must return an object without a parse error.

What if the gateway still fails after the config.json edit?

At least one 8.1.51 to 8.3.2 upgrade kept failing after the IdP file looked correct. Do not keep re-editing the same file. Restart once, take the first error of the new boot from a fresh wrapper.log, and route from there:

If no single-file fix clears the error, roll back:

1. Restore the 8.1 installation.
2. Restore the pre-upgrade .gwbk.
3. Remove the orphaned IdPs on 8.1, as described in the pre-upgrade section.
4. Upgrade again.

For escalation, send Inductive Automation support the full wrapper.log and the .gwbk, and reference IGN-13838. The complete NPE stack trace and the migration warnings are what they need to reproduce the failure.

Check: The fresh wrapper.log shows no Error during context startup after the edit or rollback.

How do you confirm the gateway and its logins work end to end?

A clean boot proves the resource decodes. It does not prove authentication works through the repaired IdP. Walk the login path hop by hop:

1. Start the service. Follow wrapper.log through startup and confirm no Error during context startup and no new IdentityProviderMigrationStrategy warnings.
2. Load the gateway web page from a remote browser, not only from localhost. This confirms the web server is listening on the network.
3. Log in to the gateway configuration pages using an account from the user source named in userSource.
4. Open the repaired IdP on the Identity Providers page. Restore the site values for rememberMeExp, sessionExp and sessionInactivityTimeout, then save from the UI. Saving from the UI lets the gateway rewrite config.json itself.
5. Launch the Designer and authenticate. If the IdP is bound to any Perspective projects, open a session and log in through it.
6. Take a new .gwbk of the working 8.3 gateway.
7. Restart the service one more time. Confirm wrapper.log reaches a clean startup again. This proves the repaired resource survives a cold decode, not just the first boot after the edit.

FAQ