Why backups fail
Most failed CLI backups trace back to one object not matching how the device behaves: the network path, the credentials, the template, the device’s prompts or the command group. This page maps what you see to where to look. The step-by-step diagnosis is in the main docs, starting at Troubleshooting Device Backups, which works through the layers in order: network, service, authentication, protocol interaction, then rConfig configuration.
Two things to know before you start
- One attempt per job. rConfig makes one connection attempt for each backup job and doesn’t retry it automatically (trap-triggered jobs are the exception). A failure stays failed until the next run.
- Debug runs behave differently. Debug and CLI runs bypass the queue and don’t time out, so they can succeed where a queued job did not. If a debug run works and the scheduled one doesn’t, look at timeouts and load, not the template.
Symptom to cause
| Symptom | Usual cause | Where it’s fixed |
|---|---|---|
| Refused or unreachable | Network path, firewall, or nothing listening on the port | Network; template port or the device’s port override |
| Fails at once, nothing in the session | Protocol not recognised (before Pro V8.3.2, SSH in capitals doesn’t match) |
Template connect.protocol |
| SSH hangs during the handshake | The device needs an older key exchange | Template kexOverride and kexAlgorithms |
| Authentication fails | Wrong credentials, or login prompts that don’t match | Device credentials; template auth prompts |
Every command returns Access denied |
The device asks for the password inside the session | Template sshInteractive, empty username (Pro V8.4.2) |
| Hangs before any prompt | A banner, splash screen or menu needs a keystroke | Template vt100 section, hpAnyKeyStatus or isMikrotik |
| Enable fails or hangs | Wrong enable password, or the enable prompt on the device is the privileged one instead of the one before enable |
Device credentials and prompts; template enableCmd, enablePassPrmpt |
| Backup completes but the file is blank | The main prompt never matched, or matched something at once | Device prompts |
| Slow, then times out | A prompt that never matches, or a timeout too short for the device or link | Device prompts; template timeout |
| Config truncated | Paging still on, or the prompt pattern matched text inside the output | Template paging and pagingCmd; device prompts |
| Each output appears under the previous command | A prompt left unread after login | Template syncToPromptOnLogin (Pro) |
| Login works, then every command times out | The device ignores a command ending in a bare carriage return | Template commandLinebreak (Pro V8.4.0, Core 8.2.19) |
| Escape codes and cursor junk in the output | The device decorates its output for a terminal | Template options.AnsiHost and setTerminalDimensions |
| A one-line command comes back empty | rConfig drops the first and last line of each response | Use a command that returns more than one line |
| Errors on some devices in a group only | A command not valid for every platform in the group | Command group |
| The config is saved on the device after each backup | A telnet template with saveConfig set |
Template saveConfig |
A timeout that is too short and a prompt that never matches look the same from outside. Raising the timeout first usually turns a fast failure into a slow one. Watch the session and see what the device sent last.
Watch the session
The fastest way to place a failure is to watch it happen. Each tool shows the session as rConfig sees it, prompt by prompt.
rConfig docsLive Debug Console (V8.2.0+)In-browser live debug console for rConfig devices: stream a debug backup run with real-time output, connection params, and rule-based recommendations.Read the docs
rConfig docsrConfig CLI Diagnostic ToolsUse the rconfig:download-device artisan command with debug to capture verbose protocol output, find connection failures, and validate prompt detection.Read the docs
The repository’s order of operations has a debugging-by-stage table that names the exact keys to check for each symptom, and it is the reference to use when this page’s table points you at the template. See the order of operations on GitHub.