What causes "Unknown format: {}. Use json, sql, or markdown" in spacedriveapp/spacedrive?

Use --format json, sql, or markdown (md also works)

spacedriveapp/spacedrive · error · anyhow::Error

Unknown format: {}. Use json, sql, or markdown

Error message

Unknown format: {}. Use json, sql, or markdown

What it means

'sd sync events export --format <value>' only accepts json, sql, markdown (md is an alias). Any other string reaches the catch-all arm and returns this error before any output is written.

Source

Thrown at apps/cli/src/domains/sync/mod.rs:481

		peer_id: query.peer_filter,
		model_type: query.model_type_filter,
		correlation_id: query.correlation_id,
		limit: query.limit,
		offset: query.offset,
		include_remote_peers: if args.all_devices { Some(true) } else { None },
	};

	let json_response = ctx.core.query(&input, Some(library_id)).await?;
	let output: sd_core::ops::sync::get_event_log::GetSyncEventLogOutput =
		serde_json::from_value(json_response)?;

	// Format output
	let formatted = match args.format.as_str() {
		"json" => format_events_json(&output.events, args.with_device)?,
		"sql" => format_events_sql(&output.events),
		"markdown" | "md" => format_events_markdown(&output.events, args.with_device),
		_ => {
			return Err(anyhow::anyhow!(
				"Unknown format: {}. Use json, sql, or markdown",
				args.format
			))
		}
	};

	// Write output
	if let Some(output_file) = &args.output {
		std::fs::write(output_file, formatted)?;
		println!("Exported {} events to {}", output.events.len(), output_file);
	} else {
		println!("{}", formatted);
	}

	Ok(())
}

fn format_events_json(

View on GitHub (pinned to 6dfeccf211)

Solutions

Use --format json, sql, or markdown (md also works)
If you need another format, export as json and convert downstream with jq or similar

Example fix

# before
sd sync events export --format csv

# after
sd sync events export --format json | jq .

Defensive patterns

Strategy: validation

Validate before calling

fn is_valid_format(s: &str) -> bool {
    matches!(s, "json" | "sql" | "markdown" | "md")
}

Type guard

fn as_format(s: &str) -> Option<&'static str> {
    match s {
        "json" => Some("json"),
        "sql" => Some("sql"),
        "markdown" | "md" => Some("markdown"),
        _ => None,
    }
}

Try / catch

let Some(fmt) = as_format(&args.format) else {
    return Err(anyhow!("Unknown format: {}. Use json, sql, or markdown", args.format));
};

Prevention

Declare the format flag as a clap enum so clap rejects invalid values with usage help
Trim and lowercase the flag value before matching
Document 'md' as an alias so users are not surprised by case sensitivity

When it happens

Trigger: Passing --format csv, txt, table, yaml, or a typo like 'jso' or 'Markdown' (matching is case-sensitive).

Common situations: Scripts assuming a format the tool never supported; uppercase first letter; trailing whitespace in shell variables.

Related errors

AI-assisted analysis of spacedriveapp/spacedrive@6dfeccf211 (2026-08-16). Data as JSON: /api/errors/09f4d67f73255fc0. Report an issue: GitHub.