From a451ef368c1b078b878c1b2e117541ac7cbdb4ae Mon Sep 17 00:00:00 2001
From: "promptless[bot]" <179508745+promptless[bot]@users.noreply.github.com>
Date: Mon, 23 Mar 2026 17:10:33 +0000
Subject: [PATCH] Add troubleshooting for Python version validation errors

---
 flash/cli/build.mdx       | 12 ++++++------
 flash/troubleshooting.mdx | 28 ++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/flash/cli/build.mdx b/flash/cli/build.mdx
index 88396834..360dd120 100644
--- a/flash/cli/build.mdx
+++ b/flash/cli/build.mdx
@@ -45,11 +45,12 @@ Comma-separated list of packages to exclude from the build (e.g., `torch,torchvi
 
 ## What happens during build
 
-1. **Function discovery**: Finds all `@Endpoint` decorated functions.
-2. **Grouping**: Groups functions by their endpoint configuration.
-3. **Manifest generation**: Creates `.flash/flash_manifest.json` with endpoint definitions.
-4. **Dependency installation**: Installs Python packages for Linux x86_64.
-5. **Packaging**: Bundles everything into `.flash/artifact.tar.gz`.
+1. **Python version validation**: Verifies your local Python version is supported (3.10, 3.11, or 3.12).
+2. **Function discovery**: Finds all `@Endpoint` decorated functions.
+3. **Grouping**: Groups functions by their endpoint configuration.
+4. **Manifest generation**: Creates `.flash/flash_manifest.json` with endpoint definitions.
+5. **Dependency installation**: Installs Python packages for Linux x86_64.
+6. **Packaging**: Bundles everything into `.flash/artifact.tar.gz`.
 
 ## Build artifacts
 
@@ -137,7 +138,6 @@ If a package doesn't have Linux x86_64 wheels:
 
 1. Ensure standard pip is installed: `python -m ensurepip --upgrade`
 2. Check PyPI for Linux wheel availability.
-3. For Python 3.13+, some packages may require newer manylinux versions.
 
 ### Need to examine generated files
 
diff --git a/flash/troubleshooting.mdx b/flash/troubleshooting.mdx
index 470605e5..6727e1e0 100644
--- a/flash/troubleshooting.mdx
+++ b/flash/troubleshooting.mdx
@@ -177,6 +177,34 @@ Duplicate route 'POST /process' in endpoint 'my-api'
 
 **Solution:** Ensure each route is unique within an endpoint. Either change the path or method of one function.
 
+## Build errors
+
+### Unsupported Python version
+
+**Error:**
+```
+Python 3.13 is not supported for Flash deployment.
+Supported versions: 3.10, 3.11, 3.12
+```
+
+**Cause:** Flash requires Python 3.10, 3.11, or 3.12.
+
+**Solution:**
+
+Switch to a supported Python version using a virtual environment:
+
+```bash
+# Using pyenv
+pyenv install 3.12
+pyenv local 3.12
+
+# Or using uv
+uv venv --python 3.12
+source .venv/bin/activate
+```
+
+Alternatively, use a Docker container with a supported Python version for your build environment.
+
 ## Deployment errors
 
 ### Tarball too large