- 4 minutes to read

Troubleshooting Installation Issues

Use these troubleshooting steps when a Nodinite v7 installation fails or components don't work as expected. Most failures come from a prerequisite that wasn't in place, so run the checks in Verify Prerequisites first; the complete list of what to prepare is on the Prerequisites page.

  • ✅ Read the pre-flight validation table the CLI prints before it deploys anything
  • ✅ SQL Server connection failures during the install
  • ✅ IIS application pools that don't start
  • ✅ Windows services that fail to install
  • ✅ A verbose CLI run, and which log file to send to our support

Understanding Where an Install Fails

The CLI first runs its pre-flight checks and prints them as a validation table. Nothing is deployed when a check fails. When all checks pass, it deploys the databases, then the IIS sites and the Windows services. Where it stops tells you which section to read.

graph LR A["fa:fa-terminal CLI run"] --> V["fa:fa-table-list Pre-flight validation"] V --> B["fa:fa-database Deploy databases"] B --> C["fa:fa-server IIS sites and application pools"] C --> D["fa:fa-cogs Windows services"] V -.->|"fails"| T["Read the Validation Table"] B -.->|"fails"| E["Database Connection Failures"] C -.->|"fails"| F["IIS Application Pool Failures"] D -.->|"fails"| G["Service Installation Failures"]

Where the CLI workflow can fail, and the section below that covers it. Most failures stop at the pre-flight validation, before anything is deployed.

Read the Validation Table

deploy-environment (also with --dry-run) starts with the same pre-flight checks as validate and prints them as a Check / Status / Details table. The checks include Runtime Environment (see Runtime Environments), IIS Prerequisites, SQL Server, Port Availability, Service Accounts, Environment (the product key), Secret Management, and Existing Installation. The table ends with Validation failed and the number of errors and warnings when a check fails.

  • Read the Details column first. It names what to fix. A wrong SQL Server name, for example, shows as SQL Server FAIL with Cannot connect to SQL Server (Main), followed by what to check in order: the server name, instance and port; the firewall; that the server's TLS certificate is trusted; and that the login is accepted.

  • Get the table without changing anything. --dry-run simulates the deployment, so it is a safe way to run the checks again after a fix:

    .\Nodinite.Installer.Cli.exe deploy-environment --config .\<server>\config.cli.json --dry-run --verbose

  • Send a screenshot of the table to our support. The log file doesn't repeat the failed checks yet (#23634), so the console table is the best evidence today.

Verify Prerequisites shows the validate and install-prerequisites commands that run the same checks before you deploy.

Database Connection Failures

If installation fails to connect to SQL Server:

  • Read the SQL Server row of the validation table - Its Details column lists what to check, in order
  • Verify SQL Server service is running - Check Services.msc or use Get-Service -Name MSSQLSERVER
  • Confirm you have sysadmin role - Run the SQL Server verification script
  • Test connection manually - Use Test-NetConnection -ComputerName SQL01 -Port 1433
  • Check firewall rules - See SQL Server Firewall
  • Verify connection string - Review encryption and certificate trust settings

SQL Server Connection Strings - Complete connection string reference

IIS Application Pool Failures

If IIS application pools fail to start:

  • Ensure the service account has the "Log on as a service" right - See Logon as a Service
  • Verify the service account password is correct - Test credentials with the runas command
  • Check the account is not locked or expired - Verify in Active Directory Users and Computers
  • Review IIS logs - Check C:\inetpub\logs\LogFiles for detailed errors
  • Verify ASP.NET Core Module V2 - Run Verify ASP.NET Core Module

IIS Windows Features - Complete IIS configuration guide

Service Installation Failures

If Nodinite services fail to install:

  • Confirm the user running the CLI has permissions - Run PowerShell 7 elevated
  • Check Windows Event Logs - Review Application and System logs for detailed error messages
  • Check the CLI troubleshooting notes - See Step 7: Run the CLI Workflow

Using Verbose Mode for Troubleshooting

Run from the extracted package root:

.\Nodinite.Installer.Cli.exe deploy-environment --config .\<server>\config.cli.json --verbose --log-file "C:\Temp\Installation-Log.txt"

Important

The --log-file path isn't written when the run fails pre-flight validation (#23633). Until that is fixed, the run is also logged to logs\Nodinite.Installer.Cli.exe-<yyyyMMdd>.log in the CLI's folder. Send that file, together with a screenshot of the validation table.

Share the log and the screenshot with our Support (Support page). The full command reference is in Step 7: Run the CLI Workflow.

Non-Interactive Runs (CI/CD)

With --non-interactive, the CLI can't prompt for the service account passwords, so they must come from environment variables:

Service Environment variable
Web Client NODINITE_WEBCLIENT_PASSWORD
Web API NODINITE_WEBAPI_PASSWORD
Log API NODINITE_LOGAPI_PASSWORD
Logging Service NODINITE_LOGGINGSERVICE_PASSWORD
Monitoring Service NODINITE_MONITORINGSERVICE_PASSWORD
MCP Endpoint NODINITE_MCPSERVER_PASSWORD

Without them, the run stops with Deployment aborted: required secrets were not provided.

Next Steps