Skip to content

docs: Add troubleshooting for Python version validation errors #580

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
muhsinking merged 1 commit into from
Mar 23, 2026
+34 −6
Merged

docs: Add troubleshooting for Python version validation errors #580

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions flash/cli/build.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Copy link
Contributor Author

@promptless promptless bot Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Citation: Added Python version validation as the first step in the build process, based on PR #261's changes to run_build() in build.py which now validates Python version unconditionally before any other build steps.
View source

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

Expand Down Expand Up @@ -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

Expand Down
28 changes: 28 additions & 0 deletions flash/troubleshooting.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor Author

@promptless promptless bot Mar 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Citation: New troubleshooting section based on the Python version validation added in PR #261. The error message and solution are derived from validate_python_version() in constants.py and the build validation in build.py.
View source


**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
Expand Down
Loading