Troubleshooting
Use guided checks and product-specific resolution steps to isolate startup, connectivity, licensing, update and administration problems before submitting a support request.
60-SECOND HEALTH CHECK
Confirm the troubleshooting baseline
Mark each item that is already confirmed. Progress is saved only in this browser.
GUIDED DIAGNOSIS
SAFE FIRST CHECKS
Choose the closest symptom
Start with the path that best matches what the administrator sees.
The application will not start
- Confirm you extracted the complete build ZIP to a local folder.
- Check Windows Properties for an Unblock option.
- Verify that appsettings.json and all build files are present.
- Review the first matching Windows Application event.
Citrix will not connect
- Complete interactive Citrix sign-in.
- Confirm the supported Citrix SDK is visible to Windows PowerShell 5.1.
- Test proxy, DNS and outbound HTTPS access.
- Run the Overview connection test and Diagnostics.
Data is missing or incomplete
- Confirm the connected site, customer or domain.
- Remove search filters and refresh the affected page.
- Verify delegated scopes and read permissions.
- Compare one known object by exact name.
An action is blocked
- Confirm the active product edition and administrative mode.
- Select the exact target required by the workflow.
- Run preview or dry-run before applying a live change.
- Check the displayed validation or permission message.
An update will not install
- Confirm you selected the incremental update ZIP.
- Verify the installed base version and Pro update entitlement.
- Redownload the official package when validation fails.
- Use the complete recovery build after a repeated rollback.
A diagnostic or report is incomplete
- Identify the single failed provider or component.
- Confirm required modules, server inputs and read permissions.
- Run a smaller component-only collection.
- Export and sanitise the original result before changes.
RESOLUTION LIBRARY
Search troubleshooting articles
Search the complete article text or filter by product area.
Typical symptoms
- No application window appears.
- The mouse cursor briefly changes and then returns to normal.
- Task Manager shows the process starting and stopping.
Resolution
- Confirm that you extracted the complete build ZIP before launching the application. Do not run the executable from inside the ZIP archive.
- Move the extracted folder to a local path such as
C:\Program Files\ITAutomatedor another approved local application folder. - Right-click the ZIP or executable, open Properties, select Unblock when displayed, and apply the change.
- Launch
ITAutomated.AdminDashboard.exefrom the extracted folder. - Open Windows Event Viewer and review Windows Logs > Application for a matching .NET Runtime or Application Error event.
When the issue remains unresolved
Record the exact time of the failed launch and attach the matching Application event. Do not send the complete Event Viewer export unless requested.
Typical symptoms
- Windows protected your PC appears.
- The executable is removed or quarantined.
- Access is denied before the application starts.
Resolution
- Confirm that the package came from the official ITAutomated customer download location.
- Verify the package name and version against your purchase or release notification.
- Use your organisation's approved file-integrity or malware-scanning process before creating any exclusion.
- When Windows SmartScreen is the only block, select More info and use Run anyway only when your security policy permits it.
- For managed endpoint security, ask the security team to review the detection rather than disabling protection globally.
When the issue remains unresolved
Provide the product name, detection name, file name, SHA-256 hash and security-product event. Never upload quarantined files through an unapproved channel.
Typical symptoms
- The splash or main window flashes and disappears.
- A configuration or permission error appears briefly.
- The application worked before a recent file replacement.
Resolution
- Confirm that all files from the complete build are present in the same installation directory.
- Do not mix files from a complete build and an incremental update manually.
- Check that
appsettings.jsonexists beside the application executable. - Restore the last complete recovery build when the failure began after a manual update.
- Review the ITAutomated logs and the Windows Application event log for the first error recorded at startup.
When the issue remains unresolved
Include the installed version, complete folder file listing, startup timestamp and first error. Remove licence keys and environment secrets before sharing.
Typical symptoms
- The first Citrix or User Session load is slow.
- A progress indicator remains active.
- Windows temporarily labels the application Not Responding.
Resolution
- Allow the current query to complete when progress is still changing. Initial Citrix cache population can take longer than later searches.
- Use the visible Cancel control rather than ending the process when the operation is cancellable.
- Confirm that the administration workstation has stable connectivity to Citrix, domain controllers and any selected remote servers.
- Close duplicate ITAutomated instances to avoid unnecessary parallel queries.
- Open Diagnostics and check the affected provider or dependency before repeating the same operation.
When the issue remains unresolved
Capture the module, selected operation, elapsed time, target environment size and timestamp. Include the related local log entries.
Typical symptoms
- The sign-in prompt does not open.
- Authentication completes but ITAutomated still reports no usable profile.
- The connection test reports an authentication failure.
Resolution
- Confirm that the workstation can reach Citrix Cloud through the organisation's proxy and firewall.
- Open ITAutomated as the same Windows user that will administer the environment.
- Select Sign in to Citrix and complete the interactive authentication prompt.
- Return to Overview and select Test Citrix connection.
- When authentication still fails, confirm that the Citrix DaaS Remote PowerShell SDK is installed and that the user has the required Citrix administrative rights.
When the issue remains unresolved
Provide the exact authentication error and timestamp. Do not include passwords, MFA codes, browser cookies or authentication tokens.
Typical symptoms
- SDK mode displays Not detected.
- Citrix pages cannot load environment data.
- The connection test reports missing modules or snap-ins.
Resolution
- For Citrix DaaS, install the supported Citrix DaaS Remote PowerShell SDK on the administration workstation.
- For on-premises CVAD, use a management workstation with the compatible Citrix PowerShell components or Studio SDK installed.
- Close all ITAutomated and Windows PowerShell processes after installing the SDK.
- Start ITAutomated again and rerun the Citrix connection test.
- Use the module inventory command in the evidence section to confirm what Windows PowerShell 5.1 can see.
When the issue remains unresolved
Attach the module inventory output showing module names, versions and paths. Do not attach the entire PowerShell module folders.
Typical symptoms
- The connection test remains active for an extended period.
- A timeout or cancellation message appears.
- Citrix Cloud works in a browser but SDK queries are slow.
Resolution
- Confirm DNS resolution and outbound HTTPS access from the workstation.
- Check whether a proxy requires authentication for PowerShell processes.
- Confirm that Citrix service health and your organisation's internet path are available.
- Retry once after closing other administrative tools that may be running large Citrix queries.
- Use Diagnostics to separate authentication, module and network failures before changing configuration.
When the issue remains unresolved
Include the start time, timeout message, proxy method and whether interactive Citrix sign-in succeeds.
Typical symptoms
- Overview reports connected but counts are zero or blank.
- One Citrix page loads while another remains empty.
- The administrator can see more objects in Citrix Studio or Web Studio.
Resolution
- Confirm that the connected Citrix customer or site is the intended environment.
- Verify the administrator's delegated Citrix scopes and roles.
- Refresh the affected page after the Overview connection test succeeds.
- Remove page filters and search text that may be hiding results.
- Compare one known object by exact name and record whether it is visible through the Citrix SDK.
When the issue remains unresolved
Provide one expected object name, the connected site/customer, applied filters and the affected page. Sanitise customer-specific names when required.
Typical symptoms
- The application displays read-only mode.
- A live action remains disabled after selecting an object.
- Preview works but Apply or Publish does not.
Resolution
- Confirm that the current product edition permits the selected module.
- Verify that a live administrative mode is enabled where the page supports it.
- Complete the required preview or validation stage before attempting a live change.
- Select exactly one valid target when the workflow requires a single selection.
- Confirm Citrix delegated permissions for the intended action.
When the issue remains unresolved
Provide the page, button name, selected object, licence edition and any validation message shown beside the control.
Typical symptoms
- Search completes with zero results.
- Exact names work but partial searches do not.
- Objects in another domain are not returned.
Resolution
- Try the exact sAMAccountName, user principal name or group name.
- Confirm the authenticated domain and whether the object belongs to another trusted domain.
- Verify that the current account can read the object's organisational unit.
- Remove leading or trailing spaces and test without a domain prefix.
- Use a domain controller parameter where the workflow provides one.
When the issue remains unresolved
Provide the object type, search format used and target domain. Replace real usernames with a safe example when possible.
Typical symptoms
- Search works but create, update or delete fails.
- A specific OU or protected object fails.
- Preview succeeds but the live operation is denied.
Resolution
- Confirm the current user shown in the ITAutomated navigation footer.
- Verify delegated permissions on the target OU, group or computer object.
- Check whether the object is protected from accidental deletion.
- Use preview or dry-run to confirm the exact objects before requesting additional rights.
- Do not run with Domain Admin rights as a general workaround; request the minimum delegated permission.
When the issue remains unresolved
Provide the operation, target OU or object type, current user and exact access-denied message. Do not include passwords.
Typical symptoms
- The target server is unreachable.
- The target user has no available policy data.
- Remote execution or WMI access is denied.
Resolution
- Confirm that the target user has logged on to the selected server.
- Test DNS resolution and administrative connectivity to the server.
- Confirm that Windows Firewall and management policy permit the required remote administration path.
- Verify that the current account has permission to query Resultant Set of Policy data.
- Retry using the server FQDN and the user in
DOMAIN\usernameformat.
When the issue remains unresolved
Include the server, user format, timestamp and exact GPResult output. Remove policy values containing secrets or internal URLs before sharing.
Typical symptoms
- Infrastructure discovery returns no servers.
- DNS NS record parsing fails.
- The authenticated domain controller is not listed.
Resolution
- Enter the complete Active Directory DNS domain name before running discovery.
- Confirm that the workstation uses a DNS server capable of resolving the target AD domain.
- Verify access to the DNS Server and Active Directory PowerShell modules required by the workflow.
- Confirm that the current identity can query DNS zones and domain controllers.
- Use preview only after selecting the discovered DNS server and domain controller.
When the issue remains unresolved
Provide the domain entered, discovery status and module-readiness results. Do not send complete DNS-zone exports.
Typical symptoms
- The server row shows unavailable or an error.
- No licence packs are returned.
- One configured server works while another fails.
Resolution
- Confirm the configured server name or FQDN.
- Test name resolution and basic network reachability from the administration workstation.
- Verify that the Remote Desktop Licensing service is running on the licence server.
- Confirm firewall and remote-management permissions required by your chosen query method.
- Use an account with read access to RDS licensing information.
When the issue remains unresolved
Provide the server name, query time and exact error. Do not attach licence keys or customer agreement details.
Typical symptoms
- A licence version is not shown in the combined summary.
- Issued or available totals differ from another console.
- Legacy licence packs appear on the server but not in the main summary.
Resolution
- Refresh the RDS licensing page and confirm that all intended servers are configured.
- Review each server row rather than relying only on the combined summary.
- Confirm the licence-pack version and licensing mode returned by the server.
- Remember that unsupported or intentionally excluded legacy versions may not appear in the headline summary.
- Compare the same timestamp and server set when validating against another tool.
When the issue remains unresolved
Include the affected server, licence-pack version, displayed totals and comparison source. Hide agreement numbers and licence keys.
Typical symptoms
- The licence signature cannot be verified.
- The key is malformed or empty.
- Activation fails immediately after pasting.
Resolution
- Copy the complete licence key without additional spaces, quotation marks or email formatting.
- Paste the key into the activation field as one uninterrupted value.
- Confirm that the key was issued by IT-Automated for the intended customer and edition.
- Verify that the Windows date and time are correct.
- Request a replacement key through the approved support channel when the supplied key remains invalid.
When the issue remains unresolved
Provide the licence ID or purchase reference and the activation error. Do not send the complete licence key in screenshots or ordinary email.
Typical symptoms
- Activation reports a machine or computer ID mismatch.
- The key worked on another administration workstation.
- Windows was rebuilt or the application was moved.
Resolution
- Open the ITAutomated licence card and copy the current computer ID.
- Confirm whether the licence is intended to be transferred from another machine.
- Deactivate the licence on the previous machine when your entitlement process supports transfer.
- Submit the current computer ID through the approved licensing channel.
- Activate only the replacement key issued for the current computer.
When the issue remains unresolved
Provide the customer name, licence ID, old computer ID when available and new computer ID. Do not send the signed activation token publicly.
Typical symptoms
- Licence status shows Validation required.
- The application reports that the Windows clock moved backwards.
- Trial or subscription status cannot be evaluated.
Resolution
- Correct the Windows date, time and time zone.
- Synchronise the workstation with the organisation's approved time source.
- Close and reopen ITAutomated after time synchronisation completes.
- Do not delete licence-state files to bypass clock validation.
- Contact support when the system clock is correct but validation still fails.
When the issue remains unresolved
Provide the current time zone, Windows time-source status and error timestamp. Do not alter or send protected licence-state files unless specifically requested.
Typical symptoms
- The licence card displays Free.
- Only the Overview experience remains available.
- Administration modules prompt for Starter or Pro activation.
Resolution
- Confirm the licence status and trial-expiry message on the Overview licence card.
- Choose Starter for perpetual module access without included updates or support, or Pro for the active subscription experience.
- Purchase the required edition through the official ITAutomated sales channel.
- Activate the issued licence for the displayed computer ID.
- Restart the application when the navigation does not refresh after successful activation.
When the issue remains unresolved
Provide the computer ID, intended edition and purchase reference. Do not include payment-card details.
Typical symptoms
- Check for updates reports that the current version is latest.
- A release exists but is not offered.
- The update check cannot access the private release source.
Resolution
- Confirm the installed version shown in the navigation footer.
- Verify that the active Pro entitlement includes software updates.
- Confirm access to the approved private update source and any required GitHub authentication used by the current build.
- Check whether the newer package is a complete recovery build rather than an incremental update.
- Use the official release notification to confirm the target version.
When the issue remains unresolved
Provide the installed version, expected version, entitlement status and update-check error. Do not provide access tokens.
Typical symptoms
- The package is rejected as an invalid incremental update.
- The update manifest is missing.
- Files were manually copied from the wrong archive.
Resolution
- Use
ITAutomated.AdminDashboard-update-[version]-win-x64.ziponly for the in-application incremental update workflow. - Use
ITAutomated.AdminDashboard-[version]-win-x64.zipfor a clean install or complete recovery. - Do not rename a complete build to look like an update package.
- Do not manually merge archives into the live application directory.
- Restore the last complete build when files were mixed manually.
When the issue remains unresolved
Provide the selected package name, installed base version and exact validation message.
Typical symptoms
- The manifest is missing or invalid.
- A package file is missing.
- SHA-256 validation fails.
Resolution
- Delete the local copy of the update ZIP.
- Download the incremental update again from the official source.
- Do not modify, extract and recreate the ZIP before applying it.
- Confirm that endpoint security did not remove or alter a package file.
- Use the complete recovery build when the official incremental package repeatedly fails validation.
When the issue remains unresolved
Provide the package name, target version and validation error. Do not upload a modified package as evidence.
Typical symptoms
- An update rollback message appears.
- The previous version reopens.
- The new version is not displayed after restart.
Resolution
- Do not repeat the same update continuously.
- Confirm that the current Windows user can write to the installation directory.
- Close antivirus scans or file-indexing operations only when approved and only for the update window.
- Confirm that no second ITAutomated process is locking application files.
- Download and deploy the complete recovery build when the incremental update cannot replace the current files.
When the issue remains unresolved
Include the old version, target version, rollback message, installation path and updater timestamp. Preserve the automatic backup until the issue is resolved.
Typical symptoms
- The report contains warnings for one dependency.
- Citrix checks succeed but AD, DNS or server checks do not.
- The overall report is available but one section is empty.
Resolution
- Treat each failed diagnostic as an isolated dependency rather than assuming the entire report is invalid.
- Open the affected finding and review its provider, target and exact error.
- Verify the required module, permission and network path for that specific check.
- Rerun only after correcting the identified dependency.
- Export the report before making changes so the original evidence is preserved.
When the issue remains unresolved
Provide the exported diagnostic report and identify the failed finding. Remove environment names or addresses when your data policy requires it.
Typical symptoms
- The report completes but one component is empty.
- A collector reports that a command is unavailable.
- Remote infrastructure details are incomplete.
Resolution
- Confirm that the missing component was selected in the Documenter plan.
- Review the component-specific inputs, server names and connection method.
- Confirm that the required Citrix, StoreFront, FAS or PVS PowerShell command is available on the collection workstation or target server.
- Verify read permission for the selected component.
- Run a smaller report containing only the affected component to isolate the failure.
When the issue remains unresolved
Include the selected plan, affected component, collection status and exact collector warning. Sanitise infrastructure names when required.
Typical symptoms
- Save reports Access is denied.
- The destination file remains locked.
- A Word report fails while HTML or JSON succeeds.
Resolution
- Select a local folder where the current Windows user has write permission.
- Close an existing report with the same file name before exporting again.
- Avoid saving directly to a restricted network share during troubleshooting.
- Test a second export format to determine whether the problem is format-specific.
- Use a short file path without unsupported characters.
When the issue remains unresolved
Provide the export format, destination type and exact error. Do not attach reports containing unreviewed credentials or sensitive configuration.
Typical symptoms
- The progress overlay remains visible.
- The first search is slower than later searches.
- Estimated remaining time changes during collection.
Resolution
- Allow the first search to build its session and machine data cache.
- Use the progress phase and elapsed-time indicators to confirm that work is continuing.
- Cancel the search when the wrong user or environment was selected.
- Confirm that large Citrix environments are not being queried through a slow or unstable connection.
- Retry after the Overview Citrix connection has been tested successfully.
When the issue remains unresolved
Include the environment size, first-search duration, later-search duration and affected username format. Replace real usernames when possible.
Typical symptoms
- Run, Publish, Delete or Apply remains disabled.
- The page asks for preview, DELETE text or explicit confirmation.
- Changing an input invalidates a previous preview.
Resolution
- Complete every required field and select the intended target.
- Run the page's preview or dry-run workflow.
- Review the proposed objects, commands and affected resources.
- Do not change an input after preview unless you run the preview again.
- Provide the required confirmation only after the preview matches the intended operation.
When the issue remains unresolved
Provide the workflow name, validation status and disabled control. Do not request removal of safety controls as a troubleshooting workaround.
No matching troubleshooting article was found
Use fewer search words, choose All topics, or prepare a support request with the exact error.
EVIDENCE COLLECTION
Collect only what supports the issue
Use the application's Open logs action first. The commands below are optional checks for the affected dependency.
Always include
- ITAutomated version
- Affected module and operation
- Exact error text and timestamp
- Expected result and actual result
- Whether preview or dry-run succeeded
Remove before sharing
- Passwords and MFA codes
- Licence keys and access tokens
- Authentication cookies
- Personal or patient information
- Unnecessary server and user lists
WINDOWS POWERSHELL
Confirm the execution host
$PSVersionTable.PSVersionCITRIX MODULES
List visible Citrix modules
Get-Module -ListAvailable Citrix* |
Sort-Object Name, Version -Descending |
Select-Object Name, Version, PathMICROSOFT MODULES
Check common RSAT modules
Get-Module -ListAvailable ActiveDirectory,DnsServer,RemoteDesktop |
Select-Object Name, Version, PathREMOTE MANAGEMENT
Test a selected server
Test-WSMan <server-fqdn>Do not run broad collection scripts in production without review.
Collect the smallest evidence set that reproduces the issue. Do not disable endpoint protection, firewall policy or product safety controls as a general troubleshooting step.
ISSUE STILL UNRESOLVED?
Submit a complete ITAutomated support request
Include the version, module, exact error, timestamp, business impact, safe reproduction steps and sanitised evidence.
Copied