Troubleshooting

Troubleshooting

Failure modes that are visible in the code, with the message you will see and what to do about it. Start with the log:

Get-Content 'C:\ProgramData\ManagedReports\logs\reportmate-*.log' -Tail 200

The run stops immediately and nothing is collected

Recent data collection detected, skipping collection (use --force to override)

A run with no module filter compares LastRunTime in HKLM\SOFTWARE\ReportMate against MaxDataAgeMinutes (default 30) and exits early if the last run was recent. Use --force, or lower MaxDataAgeMinutes. --run-module and --run-modules bypass this check entirely. A run started from the app's Run tab with every module selected is a full run, so it is subject to the check; deselect one module, or run --force from a shell.

No valid serial number

FATAL: No serial number available for device transmission. Cannot proceed.
Device registration requires a valid hardware serial number. Hostname is NOT permitted.

or, from the inventory module, an InvalidOperationException saying the device requires a valid BIOS/chassis serial.

The agent will not fall back to the hostname. It tries osquery first, then the WMI BIOS and enclosure serials, and rejects the common SMBIOS placeholders: 0, System Serial Number, To be filled by O.E.M., Default string, None, Not Specified, and anything beginning 00000000. Confirm what the firmware actually reports:

Get-CimInstance Win32_BIOS | Select-Object SerialNumber

Virtual machines and whitebox hardware frequently have no real serial. Fix it in firmware or in the hypervisor's SMBIOS settings.

A module returns nothing, but the run succeeds

Check osquery is present and answering:

managedreportsrunner.exe info -v

If OsQuery Available is False, install osquery or correct OsQueryPath. Also confirm the query packs reached ProgramData:

Get-ChildItem 'C:\ProgramData\ManagedReports\osquery\modules'

The agent self-heals a missing pack by copying it from C:\Program Files\ReportMate\osquery, and falls back to loading every module file if enabled-modules.json is missing. If the directory is empty in both places, the install was incomplete — reinstall.

Running as SYSTEM gives different results than an interactive shell

This is expected in several places and is not a bug:

• osquery running as SYSTEM gets zero rows from HKLM\SYSTEM\CurrentControlSet\Enum\DISPLAY, which is why displays are read through the root\wmi monitor classes instead.
• netsh wlan is frequently refused when Windows location services are restricted, so wireless details fall back through several detection paths.
• auditpol needs SeSecurityPrivilege; without it the security module records the failure in auditPolicy.errorMessage rather than failing the run.
• The usage tracker cannot run in session 0 at all, which is why it is a separate per-user scheduled task.

Reproduce a scheduled run faithfully by launching the binary from a SYSTEM context, not from an elevated user shell.

HTTP 400 from the API

Server rejected the compressed body; retrying uncompressed for the rest of this run

The client gzips the request body by default. An API that predates request-side compression answers 400. The client detects this and drops to uncompressed for the remainder of the run, costing one attempt. To disable compression permanently on a machine, set CompressPayload to false in HKLM\SOFTWARE\ReportMate\Settings, or by MDM in HKLM\SOFTWARE\Policies\ReportMate. The better fix is to update the API.

HTTP 404 from the API

API endpoint /api/v1/events not found (404). Endpoint may not be deployed yet.

The client treats this as success and returns exit code 0, on the assumption that the endpoint has not been deployed. The payload stays in the cache. If you see this against a live API, check that ApiUrl has no trailing path segment and that you are pointed at the API host rather than the dashboard.

Transmission fails but collection worked

Every collection writes event.json before any HTTP request, so nothing is lost. Re-send the newest cached payload:

managedreportsrunner.exe transmit -v

transmit first tests GET /api/v1/health; if that fails you get API UNREACHABLE and the payload is left alone. Because the idempotency key is derived from the payload's own collection timestamp, replaying a payload the server already accepted is deduplicated rather than double-counted.

Cache miss on transmit

CACHE MISS: No valid cache directories found

transmit only looks at directories whose names are exactly 17 characters — the yyyy-MM-dd-HHmmss format. There is no cached collection yet, or the cache was cleared. Run a collection first.

Scheduled tasks are missing or run the wrong binary

Re-check them:

Get-ScheduledTask -TaskName 'ReportMate*' | Select-Object TaskName, State, LastRunTime, LastTaskResult

If a task points at a binary that is not the version Add/Remove Programs reports, an upgrade was blocked by a locked file and the installer deferred the replacement to the next reboot. Reboot, then reinstall.

Nothing appears in the dashboard although runs succeed

Confirm which serial the payload actually routed to:

Get-ChildItem 'C:\ProgramData\ManagedReports\logs' -Directory |
  Sort-Object Name -Descending |
  Select-Object -First 1 |
  Get-ChildItem -Filter 'unified_payload_*.json'

The filename carries the serial, and the file is the exact body that was sent. Compare it against what the dashboard shows for that device. A 200 response with a module missing from the stored record is an API-side projection problem, not a client one — check the payload contains that module's object first.

Usage and application time look wrong or empty

Per-user foreground and active time comes from usagetracker.exe, which only runs in an interactive session via the ReportMate User Session Tracker task. If that task failed to register — the installer warns rather than failing — the counters under C:\ProgramData\ManagedReports\usagetracker\ never appear.

Process telemetry also depends on the post-install script having enabled either Security-log process creation auditing or the kernel process log. Both steps soft-fail, so an install can succeed with usage tracking degraded. The installer prints a warning when that happens.

Config changes have no effect

Precedence, highest first: --api-url/--device-id, the credential store, HKLM\SOFTWARE\Policies\ReportMate, HKLM\SOFTWARE\ReportMate\Settings, the deprecated legacy keys, REPORTMATE_ environment variables, then the YAML file. A value set by policy cannot be overridden by editing Settings or the YAML. Check what the agent actually resolved:

managedreportsrunner.exe info -v

Some settings are stored but not acted on by the runner, such as StorageMode, ProxyUrl and SkipCertificateValidation. Configuration lists them.

The YAML file is ignored

Settings: Ignoring C:\ProgramData\ManagedReports\appsettings.yaml: <reason>

The runner runs as SYSTEM and only reads a settings file no standard user can change. The reason names the owner or the account that holds write access. Reinstalling resets the folder's ACL. Prefer the registry: Settings locally, Policies by MDM.

The passphrase or API key is not sent

Credentials live in HKLM\SOFTWARE\ReportMate\Secrets, which only SYSTEM and Administrators can read. A run from an unelevated shell reads nothing there and sends no credential, so an API that requires one turns it away. Run from an elevated shell, as the scheduled tasks do.

A credential written to Settings or Policies is moved into the store by the next elevated run, and the readable copy is blanked. The log records each move with a Settings: line. If it says Could not verify ... in the protected store, the readable copies were left in place and the credential is still used from there.

A deprecated-key warning on every run

Settings: Using deprecated legacy registry values for ApiUrl; reinstall or upgrade ReportMate to copy them to the Settings key

HKLM\SOFTWARE\Config\ReportMate, or a value directly under HKLM\SOFTWARE\ReportMate, still supplies that setting. Reinstalling, or running managedreportsrunner.exe install --api-url <url> elevated, copies it into Settings. Then remove the legacy value, or move management to HKLM\SOFTWARE\Policies\ReportMate.

The installs module is missing from a full run

Cimian managedsoftwareupdate is currently running. Skipping Installs module collection to avoid race conditions.

A full run skips installs while Cimian is running, to avoid reading half-written reports. Runs that name modules with --run-module or --run-modules, including the Cimian postflight, skip this check.

A run hits the 30-minute task limit

Every child process the runner starts is time-bounded, so a single stalled PowerShell or tool call is killed rather than holding the run open. The usual remaining cause is a deep storage walk: only the daily hardware task should run --storage-mode deep. Check the task arguments against Installation; tasks registered with --run-modules alone fall back to auto, which walks the system volume whenever the 24-hour storage cache is stale.