astral-sh/ruff · error

Failed to format document: {stderr}

Error message

Failed to format document: {stderr}

What it means

When the `uv format` subprocess exits nonzero with stderr that is neither a parse failure nor the missing-subcommand case, the server bails with "Failed to format document: {stderr}", forwarding uv's own error text.

Source

Thrown at crates/ruff_server/src/format.rs:346

        let result = child
            .wait_with_output()
            .context("Failed to get output from format subprocess")?;

        if !result.status.success() {
            let stderr = String::from_utf8_lossy(&result.stderr);
            // We don't propagate format errors due to invalid syntax
            if stderr.contains("Failed to parse") {
                tracing::warn!("Unable to format document: {}", stderr);
                return Ok(FormatResult::Unchanged);
            }
            // Special-case for when `uv format` is not available
            if stderr.contains("unrecognized subcommand 'format'") {
                anyhow::bail!(
                    "The installed version of uv does not support `uv format`; upgrade to a newer version"
                );
            }
            anyhow::bail!("Failed to format document: {stderr}");
        }

        let formatted = String::from_utf8(result.stdout)
            .context("Failed to parse stdout from format subprocess as utf-8")?;

        if formatted == source {
            Ok(FormatResult::Unchanged)
        } else {
            Ok(FormatResult::Formatted(formatted))
        }
    }

    /// Format the entire document.
    fn format_document(&self, source: &str, path: &Path) -> crate::Result<FormatResult> {
        self.format(source, path, None)
    }

    /// Format a specific range.

View on GitHub (pinned to 26f38c119c)

Solutions

  1. Read the stderr appended to the message and fix the underlying uv-reported problem first
  2. Fix Python syntax errors in the document before formatting
  3. Check file permissions and that the file is valid UTF-8 text
  4. Run `uv format <file>` manually in the terminal to reproduce and debug outside the editor

Example fix

# before (in editor, generic failure)
# Failed to format document: error: failed to read `/path/pyproject.toml`
# after (fix pyproject / permissions, or run manually)
uv format path/to/file.py
Defensive patterns

Strategy: try-catch

Validate before calling

# pre-flight: run uv format manually on the file
import subprocess
p = subprocess.run(['uv', 'format', '--check', 'file.py'], capture_output=True, text=True)
if p.returncode != 0:
    print(p.stderr)  # shows the underlying uv error the server would surface

Try / catch

let result = std::panic::catch_unwind(|| lsp_format(uri));
// or in TS client:
try {
  await sendFormatRequest(uri);
} catch (e) {
  const msg = String(e.message ?? e);
  if (msg.startsWith('Failed to format document:')) {
    console.error('uv stderr:', msg.slice('Failed to format document:'.length));
  } else { throw e; }
}

Prevention

When it happens

Trigger: uv format failing on the document: syntax errors uv can't recover from, filesystem permission problems on the file, uv misconfiguration (bad pyproject), or environment errors reported by uv.

Common situations: Formatting a file with a Python syntax error; uv warning/failing about project environment; permission-restricted files; large or binary content passed to the subprocess.

Related errors

AI-assisted analysis of astral-sh/ruff@26f38c119c (2026-09-05). Data as JSON: /api/errors/b18cb4680ebbf80b. Report an issue: GitHub.