What causes "failed to parse auto-backup file: %s" in rqlite/rqlite?

Validate the JSON with `jq . backup.json` and fix syntax errors

failed to parse auto-backup file: %s

Error message

failed to parse auto-backup file: %s

What it means

After the auto-backup file is read, startAutoBackups() parses it with backup.NewStorageClient(), which validates the JSON config and builds the storage client (S3, GCS, MinIO, local). Invalid JSON, unknown/missing required fields (e.g. no storage type, bad region/bucket, bad interval) produce "failed to parse auto-backup file: <err>" and rqlited exits.

Source

Thrown at cmd/rqlited/main.go:318

	}

	stopProfile()
	log.Println("rqlite server stopped")
}

func startAutoBackups(ctx context.Context, cfg *Config, str *store.Store) (*backup.Uploader, error) {
	if cfg.AutoBackupFile == "" {
		return nil, nil
	}

	b, err := backup.ReadConfigFile(cfg.AutoBackupFile)
	if err != nil {
		return nil, fmt.Errorf("failed to read auto-backup file: %s", err.Error())
	}

	uCfg, sc, err := backup.NewStorageClient(b)
	if err != nil {
		return nil, fmt.Errorf("failed to parse auto-backup file: %s", err.Error())
	}
	provider := store.NewProvider(str, uCfg.Vacuum, !uCfg.NoCompress)
	u := backup.NewUploader(sc, provider, time.Duration(uCfg.Interval))
	u.Start(ctx, str.IsLeader)
	return u, nil
}

func startOTLPMetrics(cfg *Config) (*otlp.Service, error) {
	if cfg.OTLPEndpoint == "" {
		return nil, nil
	}

	srv := otlp.NewService(otlp.Config{
		Endpoint:           cfg.OTLPEndpoint,
		Interval:           cfg.OTLPMetricsInterval,
		Insecure:           cfg.OTLPInsecure,
		InsecureSkipVerify: cfg.OTLPNoVerify,
		CACertFile:         cfg.OTLPCACert,

View on GitHub (pinned to 7586a4d1bd)

Solutions

Validate the JSON with `jq . backup.json` and fix syntax errors
Compare against the auto-backup schema in the rqlite docs; ensure "storage" type and its required fields (bucket, path, region, etc.) are present and spelled correctly
Regenerate the config using a current-version example, since field names can change between rqlite versions

Example fix

// before (backup.json)
{"version": 1, "storage": {"type": "s3", "bucket": "mybucket"}}
// after
{"version": 1, "storage": {"type": "s3", "bucket": "mybucket", "path": "rqlite", "region": "us-east-1", "access_key_id": "...", "secret_access_key": "..."}}

Defensive patterns

Strategy: validation

Validate before calling

# before launching rqlited with -autobackup
if [ -n "$AUTOBACKUP_FILE" ]; then
  jq -e '.version and .storage.type and (.storage.type | IN("s3","s3-compat","gcs","azure","local"))' "$AUTOBACKUP_FILE" >/dev/null \
    || { echo "error: $AUTOBACKUP_FILE is not valid auto-backup config" >&2; exit 1; }
fi

Prevention

Always lint auto-backup JSON with jq or a JSON schema before deployment
Keep storage credentials/type fields matching the current rqlite docs version
Store the config in version control and validate it in CI

When it happens

Trigger: `rqlited -autobackup backup.json` where backup.json contains malformed JSON, an unrecognized "storage" type, missing required keys (bucket, path, region), or values of wrong type.

Common situations: Hand-edited JSON with a trailing comma; copying an example config from docs for a different storage backend; config generated by an older rqlite version using fields renamed in the current version; JSON written without a final newline by a broken templating step (usually fine) but truncation by a failed upload is not.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of rqlite/rqlite@7586a4d1bd (2026-09-03). Data as JSON: /api/errors/01ffbef001ff00b5. Report an issue: GitHub.