Troubleshooting

Most issues fall into three buckets: connection problems, authentication failures and device-type quirks. Here are the most common ones and how to resolve them.

1. 1Connection refused: the device is not listening on the expected port, or a firewall is blocking the connection. Verify with "nc -zv <host> <port>" from another machine, and confirm the port number in the device editor matches what the device is running.
2. 2Connection timeout: the host is unreachable or very slow to respond. Check the network path (ping, traceroute), increase the SSH connection timeout in Settings → SSH, and make sure the device is not rate-limiting connections.
3. 3Authentication failed: the username or password is wrong, the SSH key is not accepted, or the device does not allow the user to log in. Double-check credentials in the device editor, test with a manual "ssh user@host" from a terminal, and verify the key is in ~/.ssh/authorized_keys on the device.
4. 4Host key verification failed: the device’s SSH host key changed (common after a reinstall or image update). Delete the old key from the app’s known hosts (the session will prompt you) or from ~/.ssh/known_hosts on your machine.
5. 5Command timeout on network gear: the command took longer than the configured timeout. Increase the timeout in Settings → SSH, or break long commands into shorter ones. The app interrupts stuck commands (Ctrl+C) so the shell is recovered for the next command.
6. 6Telnet login prompt not detected: the device uses a non-standard login banner or prompt. Switch to SSH if the device supports it, or open a terminal session and log in manually — the app will learn the prompt pattern for future automated runs.
7. 7Batch run fails on some devices: one device may have a different prompt, credentials or connection issue. Check the per-device status in the batch view — failed devices show the exact error. Fix the device’s credentials or connection and re-run.
8. 8Server Desktop or Pi Desktop not loading: make sure the device type is set correctly ("server" for Server Desktop, "Raspberry Pi" for Pi Desktop). The desktop mode is only available for these device types.
9. 9Import fails with validation errors: the imported file may contain rows from an older version with missing fields. The app fills in defaults for optional fields, but required fields (name, host) must be present. Re-export from a current version of LinkOPS and try again.
10. 10App won’t start after an update: try deleting the app’s cache directory (check the FAQ in the app or the guide) and relaunching. If the problem persists, uninstall and reinstall — your data is stored in the OS keychain and database, not in the app folder.