Collector troubleshooting reference

Every collector says “Waiting for collector to start”

The current runtime launches Invoke-ISOAudit.ps1 directly and retains the actual worker PID. There is no intermediate bootstrap process and no live Worker-Launch.log redirection inside the evidence package. Confirm Live Audit Status reaches WORKER_STARTED and then a collector-specific phase. Review 04-Logs\ISO27001-Audit.log and .audit-status.jsonl for the first worker-side error.

Cancel Audit does not stop the run

Cancel writes .audit-cancel.request for cooperative shutdown. If the direct worker remains active for approximately two seconds, the GUI terminates the retained worker PID/process tree. Cancellation enforcement runs before status rendering, so a broken status/progress file cannot prevent the hard stop. Check .worker-process.json to confirm the run owns a worker PID.

Windows shows no server data

1. Open Change Credentials and reload an authorized Windows audit credential.
2. Confirm the Servers page is using the intended /24 subnets or explicit targets.
3. Verify the target responds on an applicable management path such as WinRM/WSMan, CIM/DCOM, WMI or SMB.
4. Check firewall rules, DNS/reverse DNS, RPC/DCOM, local/remote UAC restrictions and account permissions.
5. Review Target-Discovery.csv. Raw ping/RDP-only/nonresponding addresses are discovery evidence only and should not become Windows failures.
6. If an AD-known/explicit Windows server is reachable but remote audit access is blocked, expect NO_DATA / REMOTE_AUDIT_BLOCKED, not a false PASS/FAIL.

The worker validates the encrypted credential handoff before Windows collection. If the handoff cannot be reopened, the run should report a specific credential-load error rather than silently continuing with no credential.

Windows says no credential was available

Use Change Credentials, save/run again, and verify the worker-side credential validation succeeds. The credential is user-bound and encrypted; passwords are not written to report/status output. If the GUI can load the credential but the worker cannot, check the user context under which the application/worker is running and EFS/DPAPI access.

VMware/VCF.PowerCLI says Missing although installed

1. Confirm the module is installed for the PowerShell runtime that ITAuditFactory is actually using.
2. Check both Windows PowerShell 5.1 and PowerShell 7 module paths if you have mixed installations.
3. Verify VCF.PowerCLI or the expected PowerCLI modules can be imported in the same user context.
4. Use the prerequisite repair path if module discovery still reports Missing.
5. Review Program Files and PATH discovery; ITAuditFactory checks known Program Files locations as well as normal module discovery.

A module installed only for a different user or different PowerShell edition may exist on disk but still be unavailable to the assessment worker.

Linux appears when disabled

Linux Server Assessment is opt-in. Verify the checkbox is unchecked and save Settings. Current builds normalize false-like values such as False, false, 0, no, off and disabled as false. Linux must then be omitted from both worker routing and the expected Live Audit Status modules for Servers/Full.

Threads and concurrency

Valid Threads values are 1-64; 20 is supported. Lower the value if a remote platform rate-limits or has very limited management capacity. Threads controls collector concurrency; it does not control Cancel/status/PID ownership and it does not cause the former launch-log sharing violation.

Meraki/API does not connect

1. Confirm the correct Network vendor/profile and API mode are selected.
2. Re-enter/save the API key so the encrypted session secret is current.
3. Watch Live Audit Status for secret-loaded, authentication start, authenticated, or HTTP 401/403/429/TLS/DNS details.
4. Confirm outbound HTTPS/DNS to the management API is allowed.
5. Confirm the key has permission to enumerate the required organizations/networks/devices.
6. API requests use a finite timeout, so an unreachable endpoint should return an actionable error rather than wait indefinitely.

Storage authentication or encryption evidence missing

1. Confirm the Storage profile row is saved and the management address is correct.
2. For token authentication, select API key only and ensure the encrypted key exists. Owner/account metadata is optional and is not required to authenticate.
3. For password authentication, use Username + password (service account or root) where permitted.
4. For SSH collection, verify username plus key/agent and TCP/22 reachability.
5. Check the appliance API version/interface and account permissions.
6. Review TLS status separately from authenticated inventory and at-rest/data-plane encryption evidence.

Storage TLS certificate errors

Preferred fix: use the DNS name present in the appliance certificate and trust the issuing CA. This preserves strict certificate validation and produces stronger evidence than bypassing certificate trust.

If an appliance uses an approved private/self-signed certificate and evidence still must be collected, the Storage profile can enable Allow untrusted/private TLS certificate for read-only collection only. This is a per-device, collection-only exception. It does not turn the certificate finding into a pass; the invalid/untrusted certificate remains visible as a warning/Needs Review item.

Storage API key says it needs a service account

Current Storage token mode is API key only. The API key may be linked to a platform account internally, but ITAuditFactory does not require that account’s username/password to authenticate with the key. Legacy labels such as Service account + API key and REST API token remain compatibility aliases.

Evidence integrity verification fails

Do not edit stable evidence after completion. Mutable runtime telemetry/control files are intentionally excluded from the immutable evidence hash set because they can change while or after the final report is written:

.audit-progress.json
.audit-status.jsonl
.audit-cancel.request
.worker-process.json
04-Logs/ISO27001-Audit.log

Stable collector evidence, reports, CSVs, screenshots and other immutable package artifacts remain covered. Review the integrity manifest to identify the exact changed/missing file.

NO_DATA versus FAIL

NO_DATA / Not Collected means the toolkit did not obtain enough technical evidence to make the machine-evaluable determination. Investigate credentials, scope, connectivity, prerequisites or unsupported interfaces. Do not treat NO_DATA as an automatic ISO control failure. A FAIL should only be produced when applicable evidence was collected and did not meet the test expectation.

Where to find more help

Use File > Documentation for the Complete User Guide, Installation & Prerequisites, Configuration Guide, Network & API Guide, Storage & TrueNAS Guide, Backup Guide, Guided Audit Guide, IT Audit Workbench Guide, ISMS Governance Guide, Auditor Preparation Guide, Feature/Button Reference and this Troubleshooting Guide.

Run Assessment appears frozen or credential path begins with True

4.1.0 prevents PowerShell helper output from contaminating credential, Network, Backup, and Storage session handoff paths. A valid handoff is exactly one file path; it must never be rendered as True C:\...\cred_*.xml. 4.1.0 also stops recursively re-encrypting all historical evidence runs on the WPF UI thread. The Evidence Root is marked for EFS and only the newly created run directory is protected before launch.

If a current build still appears frozen before the Live Audit Status window opens, review the UI error log and confirm the Evidence Root is a local NTFS path. Threads do not begin until after the worker process starts, so changing Threads will not fix a pre-launch UI stall.