Skip to main content

Common Errors

This page lists the most frequently encountered errors, their causes, and solutions.

1. Connection Refused​

AMQP error: Connection error: Connection refused (os error 111)

Cause: The backup tool cannot reach the RabbitMQ broker on the specified host/port.

Solutions:

  • Verify RabbitMQ is running: rabbitmqctl status
  • Check the amqp_url in your config (host, port, protocol)
  • Confirm network connectivity: nc -zv rabbitmq-host 5672
  • If running in Docker/K8s, ensure the container can resolve the hostname
  • Check firewall rules allow traffic on port 5672

2. Authentication Failed​

Authentication error: ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN

Cause: The username or password in the connection URL is incorrect, or the user does not exist.

Solutions:

  • Verify the credentials in amqp_url match a valid RabbitMQ user
  • Check the user exists: rabbitmqctl list_users
  • Ensure the password does not contain unescaped special characters in the URL
  • URL-encode special characters (e.g., @ becomes %40, / becomes %2f)

3. Management API Connection Failed​

Management API error: error sending request for url (http://rabbitmq:15672/api/overview)

Cause: The Management API is not reachable.

Solutions:

  • Verify the Management Plugin is enabled: rabbitmq-plugins list | grep management
  • Enable it if missing: rabbitmq-plugins enable rabbitmq_management
  • Check the management_url in your config
  • Confirm the management port (default 15672) is accessible
  • If using HTTPS, ensure the URL scheme is https:// and port is 15671

4. Management API 401 Unauthorized​

Management API error: 401 Unauthorized

Cause: The management credentials are invalid or the user lacks the required tag.

Solutions:

  • Verify management_username and management_password in the config
  • The user needs at least the monitoring tag for backup: rabbitmqctl set_user_tags backup_user monitoring
  • For restore/definitions import, the user needs the management or administrator tag

5. Queue Not Found​

AMQP error: NOT_FOUND - no queue 'orders-queue' in vhost '/'

Cause: The specified queue does not exist on the broker, or the vhost is wrong.

Solutions:

  • List queues: rabbitmqctl list_queues -p /
  • Check your queue selection patterns in the config (include, exclude, vhosts)
  • For restore, import definitions first, or use publish_mode: direct-to-queue with create_missing_queues: true and target Management API credentials

6. Vhost Access Denied​

AMQP error: NOT_ALLOWED - access to vhost 'production' refused for user 'backup_user'

Cause: The user does not have permissions for the specified vhost.

Solutions:

  • Grant permissions: rabbitmqctl set_permissions -p production backup_user ".*" "" ".*"
  • Verify current permissions: rabbitmqctl list_permissions -p production
  • Ensure the vhost exists: rabbitmqctl list_vhosts

7. Storage Access Denied​

Storage error: Access Denied (Service: Amazon S3; Status Code: 403)

Cause: The storage credentials lack the required permissions.

Solutions:

  • Verify the access key and secret key are correct
  • Check the IAM policy grants s3:PutObject, s3:GetObject, s3:ListBucket, and s3:DeleteObject on the bucket
  • For Azure, check the account key or SAS token has read/write/list/delete permissions
  • For GCS, verify the service account has roles/storage.objectAdmin
  • Ensure the bucket name and region are correct

8. Configuration Parse Error​

Configuration error: backup.yaml: missing field `amqp_url` at line 5 column 3

Cause: The YAML configuration file has a syntax error or a missing required field.

Solutions:

  • Validate YAML syntax: python3 -c "import yaml; yaml.safe_load(open('backup.yaml'))"
  • Check for required fields: mode, backup_id, source.amqp_url, source.management_url, storage.backend
  • Ensure proper indentation (YAML is indentation-sensitive)
  • Check for unescaped special characters in strings (use quotes)

9. Backup Manifest Not Found​

Manifest error: manifest.json not found at prod/migration-001/manifest.json

Cause: The specified backup_id does not exist in the storage location, or the prefix is wrong.

Solutions:

  • List available backups: rabbitmq-backup list --path s3://bucket-name
  • Verify the prefix in your storage config matches the one used during backup
  • Check that the backup completed successfully (incomplete backups may lack a manifest)

10. Compression Error​

Compression error: invalid zstd frame header

Cause: A segment file is corrupt, was written with a different compression format, or was truncated during upload.

Solutions:

  • Run deep validation: rabbitmq-backup validate --path s3://bucket --backup-id backup-001 --deep
  • If validation fails, the segment may have been corrupted during storage upload
  • Re-run the backup for the affected queues
  • Check for network issues between the backup tool and storage

General Debugging Steps​

For any error not listed above:

  1. Enable debug logging: Add -v to the command
  2. Enable trace logging: Add -vv for maximum detail
  3. Check the RUST_LOG variable: export RUST_LOG=debug for full control
  4. Verify connectivity to both RabbitMQ (AMQP + Management API) and storage
  5. Test credentials independently (e.g., curl -u user:pass http://host:15672/api/overview)

See Debug Mode for detailed logging instructions.