Skip to main content

Common Errors and Root Cause

Avoid guesswork. Use a repeatable triage flow and classify failures quickly.

Learning Focus

Turn random failures into a playbook: identify the error class, run a minimal reproduction, then apply the correct fix.

Triage Flow​

flowchart TD
  A[Job Failed] --> B{Auth error?}
  B -->|Yes| C[Check token/key/permissions]
  B -->|No| D{Path/remote error?}
  D -->|Yes| E[Validate source and destination]
  D -->|No| F{Network/API error?}
  F -->|Yes| G[Adjust timeout/retry/TPS]
  F -->|No| H[Enable debug logging and isolate]

Error Mapping Table​

SymptomLikely classFirst checks
401/403Auth/permissionsRemote credentials, policy scope
Not found / no such filePath issueSource root, remote prefix
Timeout / context canceledNetwork/latencyTimeouts, link health, retries
Too many requestsAPI throttling--tpslimit, lower concurrency

1) Auth and Permissions​

Typical signals:

  • HTTP 401/403 errors
  • "access denied" or "invalid credentials"
  • Listing works but writes fail

First actions:

rclone config file
rclone lsd remote-prod:

Confirm the job uses the same config path and user context as your manual test.

2) Path and Targeting Mistakes​

Typical signals:

  • "not found" or "no such file"
  • Unexpected deletes in dry-run
  • Data lands in the wrong prefix

First actions:

test -d /srv/data
test "$(ls -A /srv/data | wc -l)" -gt 0
rclone lsd remote-prod:backup
rclone sync /srv/data remote-prod:backup/data --dry-run -vv

3) Network and Timeouts​

Typical signals:

  • timeouts, context canceled
  • intermittent failures that succeed on retry

First actions:

rclone sync /srv/data remote-prod:backup/data --timeout 5m --retries 8 --retries-sleep 10s

4) API Throttling​

Typical signals:

  • 429 errors
  • transfers start fast then slow sharply

Stabilization pattern:

rclone sync /srv/data remote-prod:backup/data \
  --transfers 6 --checkers 12 --tpslimit 8 \
  --retries 10 --retries-sleep 15s

Useful Debug Commands​

rclone lsd remote-prod:
rclone sync /srv/data remote-prod:backup/data --dry-run -vv
rclone config file

When You Need More Signal​

# increase logging
rclone sync /srv/data remote-prod:backup/data --dry-run -vv --log-level DEBUG --log-file /var/log/rclone-debug.log
tip

Capture logs with timestamps and include command flags in incident notes. This speeds up repeated issue resolution.

Checklist for Incident Notes​

  • Exact command executed (include flags)
  • Rclone version
  • Config path used (rclone config file)
  • Remote name and destination prefix
  • Start/end time, exit code, log file path

What's Next​