Skip to main content

Agent Troubleshooting

Diagnostic Command​

Run the built-in diagnostic tool first:

jokowipe-agent doctor
# ✓ Binary: jokowipe-agent v1.2.0
# ✓ Config: /etc/jokowipe/agent.yaml (valid)
# ✓ Token: valid format
# ✓ API: https://api.jokowipe.id reachable (23ms)
# ✓ Authentication: OK (agent-a1b2c3)
# ✓ pg_dump: found (v16.1)
# ✗ mongodump: not found
# ✓ Storage (S3): accessible (bucket: my-backups)
# ✓ Temp disk space: 45 GB free

Common Issues​

Agent Won't Connect​

Symptom: ERROR: failed to connect to api.jokowipe.id

Checklist:

  1. Test network connectivity: curl -v https://api.jokowipe.id/health
  2. Check firewall rules — outbound 443/TCP must be allowed
  3. Check DNS resolution: nslookup api.jokowipe.id
  4. Check for proxy: set HTTPS_PROXY if needed
# Test API reachability
curl -v https://api.jokowipe.id/health
# {"status":"ok","version":"1.5.0"}

With proxy:

agent:
  server_url: "https://api.jokowipe.id"
  proxy: "http://proxy.internal:8080"

Authentication Fails​

Symptom: ERROR: 401 Unauthorized — invalid or expired token

Steps:

  1. Verify the token is correctly set: echo $JOKOWIPE_AGENT_TOKEN | head -c 20
  2. Check the token hasn't been revoked in the dashboard (Settings → Agents)
  3. Generate a new token and update the config

Backup Tool Not Found​

Symptom: ERROR: pg_dump: command not found

Install the missing tool:

# Ubuntu/Debian
sudo apt-get install postgresql-client-16

# Check that it's in PATH
which pg_dump
pg_dump --version

Alternatively, specify the full path in config:

database:
  options:
    pg_dump_path: "/usr/lib/postgresql/16/bin/pg_dump"

Database Connection Refused​

Symptom: ERROR: could not connect to server: Connection refused

Checklist:

  1. Verify database is running: pg_isready -h localhost -p 5432
  2. Verify the connection string is correct
  3. Check that the backup user exists and has correct permissions
  4. Check pg_hba.conf allows connections from the agent's IP

Storage Upload Fails​

Symptom: ERROR: AccessDenied when calling PutObject

Checklist:

  1. Verify IAM permissions include s3:PutObject
  2. Check the bucket name and region are correct
  3. Verify credentials are not expired
  4. Test manually: aws s3 ls s3://my-backups/

Backup Job Times Out​

Symptom: ERROR: backup job exceeded timeout (6h)

For very large databases:

agent:
  backup_timeout: 12h    # Increase timeout

Also consider:

  • Running backups during off-peak hours
  • Excluding large non-critical tables
  • Upgrading to a machine with faster disk/network

Disk Full During Backup​

Symptom: ERROR: no space left on device

The agent writes the backup to a temp directory before uploading. Ensure /var/tmp has at least 2x the database size.

Change the temp directory:

agent:
  temp_dir: /mnt/large-disk/jokowipe-tmp

Viewing Logs​

# systemd logs (last 100 lines)
sudo journalctl -u jokowipe-agent -n 100

# Follow logs in real-time
sudo journalctl -u jokowipe-agent -f

# Logs for a specific time range
sudo journalctl -u jokowipe-agent --since "2024-01-15 02:00:00" --until "2024-01-15 03:00:00"

Enable Debug Logging​

agent:
  log_level: debug

Or via environment variable:

JOKOWIPE_LOG_LEVEL=debug jokowipe-agent start

Debug logs include full HTTP request/response details, which is helpful for diagnosing API connectivity issues.

Getting Support​

If you can't resolve the issue:

  1. Run jokowipe-agent support-bundle to collect diagnostic info
  2. Open a support ticket at app.jokowipe.id/support
  3. Attach the support bundle (it contains no secrets)
jokowipe-agent support-bundle --output ./jokowipe-support.zip
# Creates jokowipe-support.zip with:
# - Agent version and config (credentials redacted)
# - Last 500 log lines
# - System info (OS, memory, disk)
# - Network connectivity test results