25. Troubleshooting

Overview

Use this section when installation, login, discovery, or scans fail. Start with the UI error, then check the web application or scanner logs in ProgramData for the full exception.

25.1 Installer Warns About Service Account

If setup warns that the service account cannot be resolved:

1. Confirm the account is typed as DOMAIN\User, .\User, or user@domain.
2. Confirm the account exists.
3. Confirm the PI Nexus+ server can reach the domain controller.
4. Re-run setup or update identities manually after install.

If setup warns that the account could not be assigned:

1. Confirm the password is correct.
2. Confirm Log on as a batch job is granted for IIS.
3. Confirm Log on as a service is granted for the scanner service.
4. Confirm the account is not denied those rights.
5. Check domain Group Policy.
6. Update the IIS app pool and scanner service identities.

25.2 Website Does Not Open

Check:

1. IIS site PI Nexus+ exists.
2. PINexusAppPool is started.
3. Port 5139 is available.
4. Windows Authentication is enabled.
5. Anonymous Authentication is disabled.
6. Web application logs in ProgramData.

If the app pool stops immediately after starting, check the Windows Event Log and web application log. Common causes are invalid app pool identity, missing database access, or failed application startup.

25.3 /api/me or Permissions Fail

The /api/me endpoint loads current user context and permissions. If it fails, the API usually cannot initialize configuration or database access.

Check:

1. SQL bootstrap file exists.
2. SQL Server name is correct.
3. Database exists.
4. IIS app pool identity has database access.
5. Schema is compatible.
6. Web application logs show the real exception.

25.4 Database Connection Fails

Typical error:

Cannot open database "PINexus" requested by the login.
Login failed for user 'DOMAIN\svc-pinexus'.

Fix:

1. Run Setup-Database.bat as a SQL admin.
2. Confirm the service account has a SQL login.
3. Confirm the service account has a database user.
4. Confirm the service account has required permissions in the PI Nexus+ database.
5. Confirm IIS and scanner service are running as the intended service account.
6. Restart the app pool and scanner service.

25.5 PI Nexus+ Scanner Service Does Not Start

Check:

1. Windows service PI Nexus+ Scanner exists.
2. Service identity is the intended service account.
3. The account has Log on as a service.
4. SQL database is reachable.
5. Schema is compatible.
6. Scanner logs in ProgramData.

If the scanner service runs as a machine account such as DOMAIN\SERVER$, it was probably left as LocalSystem. Change it to the PI Nexus+ service account.

If Windows shows error 1053, check the scanner log for database readiness messages. A message such as PendingMigrations=1 and LatestMigration=<none> means the PI Nexus+ database exists but the schema has not been applied yet. Open Admin > SQL and click Apply, or run the database setup again, then restart the scanner service.

25.6 PI Server Discovery Fails

Check:

1. AVEVA AF SDK / PI AF Client is installed.
2. Web application logs do not report a missing Microsoft Visual C++ runtime. If they do, repair or rerun the PI Nexus+ installer.
3. Service account can access PI Data Archive and AF.
4. PI server names resolve from the PI Nexus+ server.
5. Web application logs show the AF SDK exception.

25.6.1 PI Module Database Test Fails or PI Interfaces Is Empty

Check:

1. The PI Data Archive target uses Windows authentication; OpenID Connect is not supported by the legacy Module Database API.
2. Interface Tracking is enabled for the PI Data Archive target.
3. The 64-bit PI SDK was installed on the PI Nexus+ server by using the supported setup kit from the AVEVA PI System Customer Portal.
4. IIS and the scanner service both run as the intended PI Nexus+ service account.
5. The service account can connect to the PI Data Archive and read %OSI\Interfaces.
6. Test Module DB succeeds and reports the expected Windows identity.
7. A PI Point or Full Inventory scan completed after PI SDK installation or permission changes.
8. Web application and scanner logs show the target-specific Module Database error.

If the test reports PI SDK unavailable, install or repair the 64-bit PI SDK and restart both the IIS app pool and PI Nexus+ Scanner service. If the target uses OpenID Connect, normal PI Point scanning can continue, but interface discovery requires a Windows-authenticated target.

Runtime status meanings:

• Setup Required: verify the standard UniInt marker in each health point's Extended Descriptor or configure the exact Core Health PI Point from Monitoring setup.
• Unknown: PI Nexus+ could not read the mapped core signals from PI.
• Error: readable evidence indicates a stale heartbeat, bad quality, error, or shutdown state.

25.7 AF Scan Fails

Check:

1. AF server is enabled.
2. AF database is enabled.
3. Service account has AF read access.
4. Database tests pass.
5. No other scan is running.
6. Scanner logs show the AF SDK exception.

25.8 PI Vision Scan Fails

PI Vision inventory depends on both the configured web instance and direct read access to its SQL database. Check the complete path before retrying the scan:

1. PI Vision instance is enabled.
2. PI Vision URL is correct.
3. PI Vision SQL Server and database are correct.
4. Service account has read access to the PI Vision SQL database.
5. PI Vision test passes.

25.9 License Error

Review the installed license, server binding, and licensed PI Point capacity before retrying the operation:

1. License is installed.
2. License has not expired.
3. License signature is valid.
4. PI server names match the license. New Evaluation licenses require named server bindings; legacy signed Trial licenses remain compatible and use Evaluation restrictions.
5. Current tag count is within the licensed limit, or over-capacity PI Points are expected to appear as Not Evaluated while administrators reduce scope or install a larger license.

25.10 Installer Freezes or Fails

Start with the installer diagnostics and Windows installation state:

1. Installer log in %TEMP%.
2. Installer log in ProgramData.
3. Windows Event Log source PI Nexus+ Installer.
4. Whether another MSI installation is already running.
5. Whether a previous failed install is pending reboot.

If Windows reports another installation is in progress, reboot before trying again.

25.11 PI Data Archive Discovery Returns No Servers

If PI Data Archive discovery returns no servers:

1. Confirm AVEVA AF SDK / PI AF Client is installed.
2. Confirm the PI Nexus+ service account can read the PI System connections.
3. Verify the expected PI Data Archive is present in the Connections overview in PI System Explorer.
4. Verify the PI Data Archive name resolves from the PI Nexus+ server.
5. Confirm the PI Data Archive target is enabled under Admin > PI Data Archives.
6. Review the web application log for AF SDK discovery errors.

Adding or correcting a connection in PI System Explorer does not by itself enable a PI Nexus+ target. The target must still be discovered or added and enabled in the PI Nexus+ Admin area.