Find the cause before changing the system

Installer fails

1. Confirm the machine is supported x64 Windows, the package hash is trusted and installation elevation can be approved.
2. Close any running copy of Opia and check for a pending reboot or security software blocking package files.
3. Keep the Burn and MSI logs.
4. If setup never opens a window, also preserve the newest %TEMP%\Opia\Installer\BootstrapperStartup-*.log and relevant Windows Application events.
5. If the Agent service fails to start, record sc.exe query OpiaBackgroundAgent and preserve the Agent logs before restarting anything.

Do not weaken service permissions, add broad filesystem access or introduce arbitrary delays simply to make setup complete.

Agent is missing or stale

1. Run Get-Service OpiaBackgroundAgent and confirm the service is Running and Automatic.
2. Confirm the application and Agent versions agree and that Dashboard shows the current licence state.
3. Review Dashboard and Operations for the same time period.
4. Preserve the Agent diagnostic log before restarting the service.
5. If the problem continues, generate a Diagnostic Support Bundle.

Credential or device connection fails

• Verify the management IP/hostname, DNS, routing, firewall and SSH port.
• Confirm the selected credential profile is appropriate for the device.
• Confirm the device account has the required command and enable-mode privileges.
• If the SSH host key changed, compare the displayed algorithm and fingerprint through an independent trusted channel before accepting it.
• If the Agent service identity was changed, re-enter and test affected credentials before unattended work resumes.

A Save is rejected

• Use Opia normally and unelevated as an authorised Product Administrator.
• Confirm the Agent heartbeat is current.
• Refresh the view before retrying if another change may have been saved at the same time.
• If Opia reports a configuration conflict or uncertain outcome, preserve the visible message, time and support evidence rather than editing the database directly.

Licence request or import fails

• Confirm the Agent is healthy and machine identity is available.
• Use the request exported by this retained installation.
• Confirm that the licence was issued for this Opia installation and is valid for the installed product.
• Check validity dates, capacity and entitlements.
• Do not edit .opiareq or .opialic files.

See Licensing for status-specific guidance.

Backup or fingerprint is partial or failed

• Open the operation and review its stage and per-device command outcomes.
• Check connectivity, credentials, licensing and Agent health.
• Remember that optional commands can legitimately be unsupported or unavailable on a particular platform.
• For backups, confirm show running-config returns complete output and the backup location is available.

Topology is incomplete or surprising

• Run fresh collections from both ends of the suspected relationship.
• Confirm CDP/LLDP and any relevant MAC, ARP, STP, HSRP or routing evidence is available.
• Clear current filters and review hidden/saved layout state.
• Inspect whether the link is observed or inferred before relying on it.

When to escalate

If the problem persists after the checks above, record the Opia version, Windows edition/build, issue time/time zone, affected device alias, operation/issue identifier, Agent status and the steps already taken. Generate and review a support bundle before sending it through your authorised support route.