{"record":{"id":"b18cb4680ebbf80b","repo":"astral-sh/ruff","slug":"failed-to-format-document-stderr","errorCode":null,"errorMessage":"Failed to format document: {stderr}","messagePattern":"Failed to format document: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/ruff_server/src/format.rs","lineNumber":346,"sourceCode":"\n        let result = child\n            .wait_with_output()\n            .context(\"Failed to get output from format subprocess\")?;\n\n        if !result.status.success() {\n            let stderr = String::from_utf8_lossy(&result.stderr);\n            // We don't propagate format errors due to invalid syntax\n            if stderr.contains(\"Failed to parse\") {\n                tracing::warn!(\"Unable to format document: {}\", stderr);\n                return Ok(FormatResult::Unchanged);\n            }\n            // Special-case for when `uv format` is not available\n            if stderr.contains(\"unrecognized subcommand 'format'\") {\n                anyhow::bail!(\n                    \"The installed version of uv does not support `uv format`; upgrade to a newer version\"\n                );\n            }\n            anyhow::bail!(\"Failed to format document: {stderr}\");\n        }\n\n        let formatted = String::from_utf8(result.stdout)\n            .context(\"Failed to parse stdout from format subprocess as utf-8\")?;\n\n        if formatted == source {\n            Ok(FormatResult::Unchanged)\n        } else {\n            Ok(FormatResult::Formatted(formatted))\n        }\n    }\n\n    /// Format the entire document.\n    fn format_document(&self, source: &str, path: &Path) -> crate::Result<FormatResult> {\n        self.format(source, path, None)\n    }\n\n    /// Format a specific range.","sourceCodeStart":328,"sourceCodeEnd":364,"githubUrl":"https://github.com/astral-sh/ruff/blob/26f38c119cac42e4d320ba08f09224fdec74af2c/crates/ruff_server/src/format.rs#L328-L364","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the stderr appended to the message and fix the underlying uv-reported problem first","Fix Python syntax errors in the document before formatting","Check file permissions and that the file is valid UTF-8 text","Run `uv format <file>` manually in the terminal to reproduce and debug outside the editor"],"exampleFix":"# before (in editor, generic failure)\n# Failed to format document: error: failed to read `/path/pyproject.toml`\n# after (fix pyproject / permissions, or run manually)\nuv format path/to/file.py","handlingStrategy":"try-catch","validationCode":"# pre-flight: run uv format manually on the file\nimport subprocess\np = subprocess.run(['uv', 'format', '--check', 'file.py'], capture_output=True, text=True)\nif p.returncode != 0:\n    print(p.stderr)  # shows the underlying uv error the server would surface","typeGuard":null,"tryCatchPattern":"let result = std::panic::catch_unwind(|| lsp_format(uri));\n// or in TS client:\ntry {\n  await sendFormatRequest(uri);\n} catch (e) {\n  const msg = String(e.message ?? e);\n  if (msg.startsWith('Failed to format document:')) {\n    console.error('uv stderr:', msg.slice('Failed to format document:'.length));\n  } else { throw e; }\n}","preventionTips":["Fix syntax errors before formatting","Run `uv format <file>` manually to see raw uv errors","Check file permissions and encoding","Keep uv and the pyproject configuration valid"],"tags":["ruff","lsp","formatting","uv","subprocess"],"backgroundTag":"subprocess-format-failed","analyzedSha":"26f38c119cac42e4d320ba08f09224fdec74af2c","analyzedAt":"2026-09-05T10:32:37.492Z","contentChangedAt":"2026-09-05T10:32:37.492Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}