is not a JSON file (detected ). Use `rtk read` for non-JSON…

Error message

{} is not a JSON file (detected {}). Use `rtk read` for non-JSON files. Tip: use `rtk deps` for Cargo.toml.

What it means

`rtk json` only processes files whose extension identifies a JSON format (.json, .jsonc, .json5). When given another extension it bails, telling you to use `rtk read` for plain files — and if it detects a TOML file named Cargo.toml it additionally points you at the purpose-built `rtk deps` command.

Solutions

For Cargo.toml use `rtk deps` (the dedicated manifest reader).
For non-JSON files use `rtk read <file>` to view content with filtering.
Verify the file extension/correct path — you may have grabbed the wrong file when two similarly named configs exist (.json vs .yaml).
If the file genuinely is JSON, rename or fix the extension so it matches its content.

Example fix

// before
rtk json Cargo.toml
// after
rtk deps Cargo.toml   # or: rtk read config.yaml for non-JSON files

Defensive patterns

Strategy: validation

Validate before calling

const JSON_EXTS = new Set(['.json', '.jsonc', '.json5']);
function ensureJsonFile(path) {
  const ext = path.slice(path.lastIndexOf('.'));
  if (!JSON_EXTS.has(ext)) {
    throw new Error(`${path} is not JSON; use rtk deps for Cargo.toml, rtk read otherwise`);
  }
  return path;
}

Type guard

fn is_json_file(p: &Path) -> bool {
    matches!(p.extension().and_then(|e| e.to_str()), Some("json") | Some("jsonc") | Some("json5"))
}

Try / catch

match rtk_json(file) {
    Err(e) if e.to_string().contains("is not a JSON file") => {
        let ext = file.extension().unwrap_or_default();
        if file.ends_with("Cargo.toml") { run("rtk deps Cargo.toml")?; }
        else { run(&format!("rtk read {}", file.display()))?; }
    }
    other => other?,
}

Prevention

Check the file extension before routing to `rtk json`; use `rtk deps` for Cargo.toml and `rtk read` for everything else.
In batch jobs, filter the file list to *.json/*.jsonc/*.json5 first.
Keep .json and .yaml config twins clearly named to avoid grabbing the wrong file.

When it happens

Trigger: Running `rtk json <file>` where <file> ends in .toml, .yaml, .yml, .txt, etc.; calling validate_json_extension directly with a non-JSON path; explicitly rejected cases covered by tests: any .toml file, Cargo.toml specifically, and .yaml files.

Common situations: Typing `rtk json Cargo.toml` out of habit instead of `rtk deps`; pointing the json filter at a YAML config because the content looks structured; automating over a directory of mixed config files without checking extensions first.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

AI-assisted analysis of rtk-ai/rtk@0924356b4c (2026-09-19). Data as JSON: /api/errors/a030a5d1c8a69207. Report an issue: GitHub.

Appendix: source

Thrown at src/cmds/system/json_cmd.rs:35

            "toml" => Some("TOML"),
            "yaml" | "yml" => Some("YAML"),
            "xml" => Some("XML"),
            "csv" => Some("CSV"),
            "ini" => Some("INI"),
            "env" => Some("env"),
            "txt" => Some("plain text"),
            _ => None,
        };
        if let Some(fmt) = format_name {
            let mut msg = format!(
                "{} is not a JSON file (detected {}). Use `rtk read` for non-JSON files.",
                file.display(),
                fmt
            );
            if ext == "toml" && file.file_name().is_some_and(|n| n == "Cargo.toml") {
                msg.push_str(" Tip: use `rtk deps` for Cargo.toml.");
            }
            bail!("{}", msg);
        }
    }
    Ok(())
}

/// Show JSON (compact with values by default, or keys-only with --keys-only)
pub fn run(file: &Path, max_depth: usize, schema_only: bool, verbose: u8) -> Result<()> {
    validate_json_extension(file)?;
    let timer = tracking::TimedExecution::start();

    if verbose > 0 {
        eprintln!("Analyzing JSON: {}", file.display());
    }

    let content = fs::read_to_string(file)
        .with_context(|| format!("Failed to read file: {}", file.display()))?;

    let shown = render_json(&content, max_depth, schema_only)?;

View on GitHub (pinned to 0924356b4c)