- 8 minutes to read

Troubleshooting Nodinite Installations and Upgrades

Important

Before troubleshooting, make sure you run the latest available Nodinite version.

  • Latest updates include security fixes and platform compatibility updates.
  • Active support may require you to update before deeper troubleshooting starts.
  • Use the Updating Nodinite v7 guide to get current.

This page is the starting point when a Nodinite v7 installation or update does not go as planned. It sends you to the right troubleshooting guide, shows where the diagnostic logs are, and tells you how to reach support.

✅ One entry point for every installation and update problem
✅ How to access and use Nodinite's built-in diagnostic logs
✅ Guidance for IIS, Windows Server, SQL Server, and OAuth 2.0 issues
✅ Direct support contact for fast resolution

Find the Right Guide

On Windows Server, a v7 installation starts in the Nodinite Portal wizard (Install Nodinite v7 Steps) and ends with the CLI running the generated package in elevated PowerShell 7 (Step 7). Where it fails tells you which guide to open.

flowchart TD START["fa:fa-circle-question What is failing?"] START -->|"CLI validate or deploy stops"| CLI["fa:fa-terminal Step 7 CLI troubleshooting
--verbose, file locks"] START -->|"Web Client, Web API or Log API
not reachable or sign-in fails"| IIS["fab:fa-windows IIS troubleshooting
TLS, authentication, SPN"] START -->|"Windows service does not start"| WIN["fa:fa-server Windows Server troubleshooting
Logon as a Service, gMSA, MSDTC"] START -->|"Database errors"| SQL["fa:fa-database SQL Server troubleshooting"] START -->|"OAuth 2.0 token or claim errors"| OAUTH["fa:fa-key OAuth 2.0 troubleshooting"] START -->|"Off-site Monitoring Agent unreachable"| RELAY["fa:fa-cloud Service Bus Relaying"] START -->|"Container sandbox"| CONT["fab:fa-docker Runtime Environments"] style START fill:#2678BD style CLI fill:#E47528 style IIS fill:#3F827B style WIN fill:#3F827B style SQL fill:#3F827B style OAUTH fill:#3F827B style RELAY fill:#9E59BB style CONT fill:#9E59BB

Decision tree: start from the symptom (blue). Installer problems (orange) go to Step 7: Install the Generated Package; platform problems (teal) go to the IIS, Windows Server, SQL Server, and OAuth 2.0 guides; distributed setups (purple) go to Service Bus Relaying and Runtime Environments.

Tip

If you are reading this, make sure to review the prerequisites first: the Prerequisites page, and the v7 prerequisites summary. Firewall ports are listed only in the Network and Firewall Overview.

Diagnostic Logs

Nodinite provides built-in trace logging using a rolling log file appender with JSON output. These logs are essential for troubleshooting and are the first thing our support team will request if you encounter issues.

Almost all Nodinite applications generate these logs wherever installed. In v7 on Windows Server, each Core Service and each IIS-hosted agent writes them to the DiagnosticsFiles folder of its own IIS web site, for example Nodinite-<Environment>-LogAPI. For the CLI, add --verbose, and --log-file <Path> to save the output; see Step 7: Run the CLI Workflow. However, if the account running the application lacks change/write rights, the log files cannot be created.

If you are missing the diagnostic files, review the How to set Logon as a Service Right user guide.

Diagnostic files
Here's an example of the rolling diagnostic files.

For Monitoring Agents, you can download all diagnostic files as a single ZIP for easy sharing with support. See the Add or manage Monitoring Agent - Diagnostics user guide for details.

For installer failures, rerun the CLI command with --verbose; see Using Verbose Mode for Troubleshooting.

What IIS Authentication settings do I need?

On Windows Server, every Core Service that serves HTTP (Web Client, Web API, Log API) is its own IIS web site. For secure and reliable access, follow the steps in the IIS Authentication settings user guide.

Why are animations not played?

If you are browsing the Web Client locally on a Windows Server, you may notice that animations are not played. This is due to Windows performance settings—either Adjust for best performance or Let Windows choose what's best for my computer—which Font Awesome version 6 and later honors by default.

To enable animations:

  1. Open sysdm.cpl.
  2. Click the Advanced tab.
  3. Click the Settings button in the Performance panel.
  4. On the Visual Effects tab, choose Custom (with all animation options checked) or Adjust for best appearance.

Frequently Asked Questions

Can I skip monthly Nodinite updates for a few months?

Your installation keeps working, but we recommend applying updates as soon as possible to keep security and support eligibility:

  • Per your software agreement, active support coverage requires running the latest available version of Nodinite.
  • Nodinite follows Microsoft's monthly .NET patch cycle; skipping updates means missing security patches for known vulnerabilities.
  • Skipping several update cycles makes the next update larger and requires more thorough testing.

Download each monthly update, test it in your non-production environment, then apply it to production. The full strategy is in Stay up-to-date.

Tip

If business constraints prevent updates for an extended period, read more on the Support page or contact your partner in advance to discuss your specific situation. Documented exceptions can be made for critical business periods.

Nodinite v6 is no longer supported and receives no updates. Plan your move with Updating from v6 to v7.

Is being on the latest version required for support?

Yes, in most cases. Nodinite support is tied to running the latest available version so we can:

  • verify known security fixes are applied
  • troubleshoot against the currently supported codebase
  • avoid spending time on issues already fixed in recent updates

If a critical production situation blocks immediate updating, contact Support page and describe your constraints so we can guide the safest path forward.

How often does Nodinite release updates?

Nodinite follows a monthly release cadence aligned with Microsoft's .NET patch cycle. New releases are typically available within days of Microsoft's monthly patches, ensuring you benefit from the latest security updates, performance improvements, and new capabilities.

What if a critical bug is found in the latest version?

While we strive for quality through rigorous testing, if a critical bug is discovered in a released version, we follow this process.

Immediate Response

  • Hotfix Release - Critical bugs are addressed with priority hotfix releases, typically within hours or days depending on severity
  • Customer Notification - Affected customers are notified immediately via email and the Nodinite Portal
  • Workaround Guidance - If available, temporary workarounds are provided while the fix is developed

Rollback Support

  • If a critical bug severely impacts your production environment, read more on the Support page to learn how to get in touch
  • We will provide guidance on temporary rollback to the previous stable version while maintaining your support coverage
  • Your support agreement remains valid during documented rollback scenarios for critical bugs

Quality Assurance

  • We recommend testing updates in non-production environments before applying to production
  • Early adopters and partners often test releases before wider deployment, providing additional validation
  • Always back up your environment before applying updates to enable quick recovery if needed

Important

Critical Bug Policy: If you discover a critical bug in the latest release:

  1. Contact Support page immediately with full details
  2. Do NOT apply the update to additional environments until we provide guidance
  3. Your support agreement remains active if you rollback to the previous stable version due to a confirmed critical bug
  4. We will prioritize a hotfix release and keep you informed throughout the process

This is why we recommend a phased rollout strategy: test in non-production first, then gradually apply to production environments.

Contact our support

If you have any questions or encounter problems with Nodinite installations or upgrades, contact our support team at Support page.

Next Steps

Install and Update

SQL Server

IIS and Windows Server

Azure, OAuth 2.0, and Containers

Legacy (v6 and earlier)