GitoxideLabs/gitoxide · info · anyhow::Error

JSON output isn't yet supported for listing ref-mappings.

Error message

JSON output isn't yet supported for listing ref-mappings.

What it means

The `gix refs` tracking-ref-mappings command refuses to run when a non-human (JSON) output format is requested. Listing ref-mappings (local-to-remote ref mapping) simply has no JSON serializer implemented yet in gitoxide-core, so the code bails out early before doing any work. It is an explicit not-yet-implemented guard, not a failure of the operation itself.

Solutions

1. Drop `--format json` and use the default human output for this subcommand
2. Check the gitoxide version/changelog for when JSON output for ref-mappings lands and upgrade
3. Request or contribute JSON serialization support for ref-mappings in gitoxide-core
4. Parse the human output yourself as a temporary workaround

Example fix

// before
gix refs --tracking --format json
// after
gix refs --tracking

// caller-side (shell)
if [[ "$requested_format" != "human" ]]; then
  echo "refs ref-mapping listing only supports human output" >&2; exit 2
fi
gix refs --tracking --format "$requested_format"

# bash
if ! out=$(gix refs --tracking --format json 2>&1); then
  case "$out" in *"isn't yet supported"*) out=$(gix refs --tracking);; esac
fi

When it happens

Trigger: Running `gix refs ... --format json` (OutputFormat::Json) for the refs::Kind::Tracking path that lists ref-mappings in `gitoxide-core/src/repository/remote.rs::refs_fn`. The `bail!` fires whenever `format != OutputFormat::Human` and the kind is Tracking.

Common situations: Scripting/automation users pass `--format json` for machine-readable output of tracking ref mappings; docs or tab-completion suggest a JSON format that other subcommands support but this one does not yet.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• JSON output isn't implemented yet
• Only human output is currently supported
• Only human format is supported right now
• Only human output is supported for now
• JSON output isn't supported

AI-assisted analysis of GitoxideLabs/gitoxide@e73179060b (2026-09-08). Data as JSON: /api/errors/5497e385e4949f05. Report an issue: GitHub.

Appendix: source

Thrown at gitoxide-core/src/repository/remote.rs:97

        kind: refs::Kind,
        mut progress: impl gix::Progress,
        mut out: impl std::io::Write,
        err: impl std::io::Write,
        refs::Options {
            format,
            name_or_url,
            handshake_info,
        }: refs::Options,
    ) -> anyhow::Result<()> {
        use anyhow::Context;
        let mut remote = by_name_or_url(&repo, name_or_url.as_deref())?;
        let show_unmapped = if let refs::Kind::Tracking {
            ref_specs,
            show_unmapped_remote_refs,
        } = &kind
        {
            if format != OutputFormat::Human {
                bail!("JSON output isn't yet supported for listing ref-mappings.");
            }
            if !ref_specs.is_empty() {
                remote.replace_refspecs(ref_specs.iter(), gix::remote::Direction::Fetch)?;
                remote = remote.with_fetch_tags(gix::remote::fetch::Tags::None);
            }
            *show_unmapped_remote_refs
        } else {
            false
        };
        progress.info(format!(
            "Connecting to {:?}",
            remote
                .url(gix::remote::Direction::Fetch)
                .context("Remote didn't have a URL to connect to")?
                .to_bstring()
        ));
        let (map, handshake) = remote
            .connect(gix::remote::Direction::Fetch)

View on GitHub (pinned to e73179060b)