diff --git a/README.md b/README.md index f6fae93e..d4f4bb32 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,25 @@ Preview URL: https://skill-deploy-abc123.vercel.app Claim URL: https://vercel.com/claim-deployment?code=... ``` +### vercel-python + +Diagnose, fix, and prepare Python projects for Vercel deployments. Complements the deployment and CLI token skills with Python-specific runtime, framework, and dependency guidance. + +**Use when:** +- Deploying FastAPI, Flask, Django, or generic ASGI/WSGI apps to Vercel +- Fixing Python entrypoint, handler, or framework detection errors +- Debugging `pyproject.toml`, `requirements.txt`, `uv`, lockfile, or `.python-version` issues +- Investigating Python bundle size, runtime dependency installation, or Vercel Python diagnostics +- Using the Vercel Python SDK or runtime helper APIs + +**Categories covered:** +- Entrypoint and callable discovery +- FastAPI, Flask, and Django deployment patterns +- Python version and dependency manifest selection +- `uv` and lockfile behavior +- Bundle size and runtime dependency troubleshooting +- Vercel Python SDK and runtime APIs + ## Installation ```bash diff --git a/skills/vercel-python.zip b/skills/vercel-python.zip new file mode 100644 index 00000000..4f853c11 Binary files /dev/null and b/skills/vercel-python.zip differ diff --git a/skills/vercel-python/SKILL.md b/skills/vercel-python/SKILL.md new file mode 100644 index 00000000..fc1d73e0 --- /dev/null +++ b/skills/vercel-python/SKILL.md @@ -0,0 +1,88 @@ +--- +name: vercel-python +description: Diagnose, fix, and prepare Python projects for Vercel deployments. Use for FastAPI, Flask, Django, ASGI/WSGI, Python entrypoints, pyproject.toml, requirements.txt, uv, .python-version, bundle size, Python runtime errors, or Vercel's Python SDK/runtime APIs. Use this skill whenever the user mentions Python and Vercel in the same context, even if they don't explicitly ask for deployment help. +metadata: + author: vercel + version: "1.0.0" +--- + +# Vercel Python + +Use this skill when a Vercel deployment involves Python, including FastAPI, Flask, Django, generic ASGI/WSGI apps, Python runtime diagnostics, dependency resolution, Python version selection, bundle size issues, or the `vercel` Python SDK. + +This skill diagnoses and fixes Python-specific deployment issues. It does not handle the deployment itself. + +## How It Works + +1. **Inspect the project structure** before changing any files. Check the following: + + **Entrypoint:** Identify the app entrypoint and confirm it exposes a supported top-level callable (`app`, `application`, or `handler`). The entrypoint priority is: `[tool.vercel].entrypoint` in `pyproject.toml`, then framework-specific discovery (Django uses the settings module; others use conventional files like `app.py`, `main.py`, etc.), then `[project.scripts].app` (legacy). For Django projects, if `manage.py` exists at the root or one directory below, check that the settings module defines `ASGI_APPLICATION` or `WSGI_APPLICATION`. See `references/runtime-and-entrypoints.md` for full details. + + **Dependencies:** Identify the dependency manifest. Vercel discovers manifests from the entrypoint directory upward to the project root. The highest-priority manifest wins: `pyproject.toml` > `Pipfile.lock` / `Pipfile` > `requirements.txt` (and variants like `requirements.frozen.txt`, `requirements.in`, `requirements/prod.txt`). Check for a lockfile: `uv.lock` or `pylock.toml` (used with `pyproject.toml` projects). See `references/dependencies-and-versions.md` for the full priority list. + + **Bundle size:** Vercel Python functions support up to [500 MB](https://vercel.com/docs/functions/limitations#bundle-size-limits). Do not use 250 MB as the limit. When a `uv.lock` is present, the builder can automatically externalize large public PyPI packages and install them at cold start, allowing even larger dependency sets. See `references/dependencies-and-versions.md` for size reduction strategies. + + **Python version:** Check `.python-version` (takes priority) and `project.requires-python` in `pyproject.toml`. Vercel supports Python 3.12, 3.13, and 3.14 for new projects. Only flag a version as blocking if it excludes all supported versions (e.g., `==3.11.*`, `<3.12`, `>=3.15`). A range like `>=3.11` is fine because it includes 3.12+. + + **Database:** If the project requires a database (PostgreSQL, MySQL, etc.), note that Vercel Marketplace provides managed database integrations (Neon Postgres, Supabase, AWS RDS) that automatically set connection environment variables. Do not assume the app cannot connect to a database on Vercel. See `references/frameworks.md` for details. + + **Vercel config:** If `vercel.json` exists, check for custom `buildCommand` or `installCommand` (these can limit dependency optimization). + + **Monorepo:** If the Python app is in a subdirectory of a monorepo, confirm `rootDirectory` is set correctly in the Vercel project settings. The builder resolves `uv.lock` from the workspace root automatically for uv workspace projects. + + **Background workers:** If the project uses task queues, background jobs, or event-driven workers (Celery, Dramatiq, Django tasks, or similar), check `references/frameworks.md` for Vercel's worker service support via the `vercel-workers` package. Do not assume background processing is incompatible with Vercel. + +2. **Identify blockers and risks** from what you found: + - **Blocking:** No entrypoint file and no configurable path, no callable symbol, Python version that excludes all supported versions, malformed config files, Django without `manage.py`. + - **Risk:** No dependency manifest, custom build/install commands, Django without ASGI/WSGI settings. + - **Info:** Which manifest, lockfile, and Python version source were detected. Nonstandard entrypoint path (fixable with `[tool.vercel].entrypoint`). + +3. Read only the reference file that matches the problem: + - Entry points and runtime behavior: `references/runtime-and-entrypoints.md` + - Dependency manifests, `uv`, and Python versions: `references/dependencies-and-versions.md` + - FastAPI, Flask, Django, and static assets: `references/frameworks.md` + - Build/runtime errors: `references/troubleshooting.md` + - Python SDK and runtime helpers: `references/sdk-runtime-apis.md` + +4. Make the smallest safe project change that addresses the root cause, or give the user exact remediation when credentials, missing env vars, or account state block progress. + +5. **Verify.** Re-check the project against the same checklist from step 1. Confirm that no blocking findings remain and all risks have been documented or addressed. + +## Exit Criteria + +This skill's job is done when the Python project has no blocking deployment issues. It does not handle deployment, auth, environment variables, domains, or logs. + +## Common Misconceptions + +Do not accept these conclusions without checking the reference docs first: + +| Claim | Reality | +|---|---| +| "The bundle is too large for Vercel" | The limit is 500 MB, not 250 MB. With `uv.lock`, the builder externalizes public packages beyond that. | +| "This app requires a database, so it can't deploy to Vercel" | Vercel Marketplace provides Neon Postgres, Supabase, and AWS RDS integrations. | +| "Background processing is impossible on Vercel" | Vercel supports worker services via `vercel-workers` with Celery, Dramatiq, and Django task adapters. | +| "Vercel doesn't support uv workspaces or monorepos" | It does. The builder resolves `uv.lock` from the workspace root. | +| "This entrypoint path isn't supported" | Any path works with `[tool.vercel].entrypoint` in `pyproject.toml`. | +| "Python version X.Y isn't compatible" | Only blocking if the range excludes all of 3.12, 3.13, and 3.14. Ranges like `>=3.11` are fine. | + +## Present Results to User + +Lead with the concrete blocker or readiness status: + +```text +I inspected the Python project. Vercel should use `app/main.py` as the entrypoint with `app` as the ASGI callable. No blocking issues found. +``` + +When several findings exist, group them by deployment impact: + +- Blocking: prevents Vercel from building or routing the app. +- Risk: likely runtime failure or slow/large deployment. +- Info: useful context such as manifest, lockfile, or detected entrypoint. + +## Troubleshooting + +- Entrypoint or handler not found: inspect `references/runtime-and-entrypoints.md`. +- Dependency sync, `uv`, lockfile, or Python version issues: inspect `references/dependencies-and-versions.md`. +- FastAPI, Flask, Django, static assets, or `collectstatic` issues: inspect `references/frameworks.md`. +- Vercel diagnostic codes such as `PYTHON_ENTRYPOINT_NOT_FOUND`, `PYTHON_HANDLER_NOT_FOUND`, `DJANGO_SETTINGS_FAILED`, `PYTHON_REQUIREMENTS_PARSE_ERROR`, `PYTHON_DEPENDENCY_SYNC_FAILED`, or `LAMBDA_SIZE_EXCEEDED`: inspect `references/troubleshooting.md`. +- Runtime helper APIs such as Blob storage, OIDC, caching, geolocation, or cron scheduling: inspect `references/sdk-runtime-apis.md`. diff --git a/skills/vercel-python/metadata.json b/skills/vercel-python/metadata.json new file mode 100644 index 00000000..7962dc82 --- /dev/null +++ b/skills/vercel-python/metadata.json @@ -0,0 +1,13 @@ +{ + "version": "1.0.0", + "organization": "Vercel", + "date": "April 2026", + "abstract": "Diagnose, fix, and prepare Python projects for Vercel deployments, including FastAPI, Flask, Django, ASGI/WSGI entrypoints, dependency manifests, Python versions, bundle size, and Python SDK/runtime helpers.", + "references": [ + "references/runtime-and-entrypoints.md", + "references/dependencies-and-versions.md", + "references/frameworks.md", + "references/troubleshooting.md", + "references/sdk-runtime-apis.md" + ] +} diff --git a/skills/vercel-python/references/dependencies-and-versions.md b/skills/vercel-python/references/dependencies-and-versions.md new file mode 100644 index 00000000..3274198b --- /dev/null +++ b/skills/vercel-python/references/dependencies-and-versions.md @@ -0,0 +1,102 @@ +# Dependencies and Versions + +Use this reference for `pyproject.toml`, `requirements.txt`, `Pipfile`, `uv`, lockfiles, Python version diagnostics, dependency sync failures, and large bundle behavior. + +## Manifest Priority + +Vercel discovers Python dependencies from the entrypoint directory upward to the project root. The effective priority is: + +1. `pyproject.toml` +2. `Pipfile.lock` +3. `Pipfile` +4. `requirements.frozen.txt` +5. `requirements-frozen.txt` +6. `requirements.txt` +7. `requirements.in` +8. `requirements/prod.txt` + +Prefer `pyproject.toml` for new projects. Use one primary manifest to avoid confusing agents and future maintainers. + +## Lockfile Priority + +When using `pyproject.toml`, lockfiles are selected in this order: + +1. `uv.lock` +2. `pylock.toml` + +`Pipfile.lock` is for Pipfile-based projects and should not be treated as the lockfile for a `pyproject.toml` project. + +## Python Versions + +Vercel Python deployments currently support Python 3.12, 3.13, and 3.14 for new projects. Python 3.12 is the default. See [Vercel Python documentation](https://vercel.com/docs/functions/runtimes/python) for the current list of supported versions. + +Vercel uses major.minor only; patch numbers in `.python-version` or `requires-python` are ignored. + +Version selection sources: + +1. Nearest `.python-version` +2. `project.requires-python` in `pyproject.toml` + +Use `.python-version` when the desired exact runtime matters: + +```text +3.13 +``` + +Use `requires-python` for package compatibility. A bounded range allows Vercel to select the best supported version: + +```toml +[project] +requires-python = ">=3.12,<3.15" +``` + +A wildcard equality pin locks to a specific minor version: + +```toml +[project] +requires-python = "==3.12.*" +``` + +Both patterns are valid. Do not request unsupported future versions such as `3.15`. + +## uv Behavior + +Vercel uses `uv` for Python dependency installation. Build-time installs can download managed Python versions automatically. Runtime dependency installation avoids Python downloads and expects the needed runtime to be available. + +The builder supports **uv workspaces**. When the project is a workspace member, the builder resolves `uv.lock` from the workspace root automatically. Do not claim that uv workspaces or monorepo layouts are unsupported. + +If dependency sync fails: + +1. Reproduce locally with `uv sync` or `uv pip install -r requirements.txt`. +2. Check native extensions and platform-specific wheels. +3. Confirm the selected Python version satisfies all dependencies. +4. Remove stale or conflicting lockfiles. + +## Custom Build or Install Commands + +Custom `installCommand` or `buildCommand` can disable or limit Vercel's Python dependency optimization. Avoid custom commands unless the project genuinely needs them. + +When custom commands are required, document why and keep them minimal. + +## Bundle Size + +Vercel Python functions support up to [500 MB](https://vercel.com/docs/functions/limitations#bundle-size-limits) of total bundle size. + +When a project exceeds the standard bundle limit and a `uv.lock` is present, the builder can automatically externalize public PyPI packages. Externalized packages are installed at cold start from the lockfile rather than bundled into the function. This is the primary mechanism for deploying large Python dependency sets. It requires: + +- `pyproject.toml` with a `uv.lock` lockfile. +- No custom install or build commands (these disable the optimization). + +Strategies for reducing function size: + +- **Use `uv.lock` with `pyproject.toml`** so the builder can externalize large public packages. This is the most effective fix for heavy dependency sets. +- **Separate production from dev dependencies.** Use optional dependency groups or `[dependency-groups]` in `pyproject.toml` to keep test, lint, and build tools out of the production install. Vercel installs only main dependencies by default. +- **Audit heavy packages.** Check whether packages like numpy, pandas, scipy, or spacy are actually needed at runtime. If they are only used in data pipelines or scripts, remove them from the deployed function's dependencies. +- **Consider lighter alternatives.** For example, `polars` is significantly smaller than `pandas` for data processing. `httpx` or `urllib3` can replace heavier HTTP libraries. +- **Remove committed artifacts.** Do not commit `.venv`, `venv`, `__pycache__`, model weights, or generated files. These inflate the bundle. +- **Use `excludeFiles` in `vercel.json`** only for files that are safe to omit from the function bundle. +- **Avoid custom install/build commands** when the issue is dependency bundle size -- these disable the externalization optimization. + +The externalization mechanism handles public PyPI packages. Private packages (git, local path, or non-PyPI registries) are always bundled directly. + +Do not assume Vercel deploys every local file. Static `public/**` assets are served separately, and many development/cache directories are excluded. diff --git a/skills/vercel-python/references/frameworks.md b/skills/vercel-python/references/frameworks.md new file mode 100644 index 00000000..a53fb9a0 --- /dev/null +++ b/skills/vercel-python/references/frameworks.md @@ -0,0 +1,144 @@ +# Frameworks + +Use this reference for FastAPI, Flask, Django, ASGI/WSGI app shape, static files, and framework-specific deployment friction. + +## Zero Configuration + +Correctly structured Python projects deploy with zero configuration. No `vercel.json` is needed when the entrypoint and callable follow Vercel's conventions. Do not create a `vercel.json` unless the project genuinely needs an override — unnecessary config is a common source of deployment failures. + +## FastAPI + +Minimal entrypoint: + +```python +from fastapi import FastAPI + +app = FastAPI() + + +@app.get("/") +def read_root(): + return {"ok": True} +``` + +FastAPI is ASGI. Declare both `fastapi` and an ASGI server such as `uvicorn` in the dependency manifest. WSGI frameworks like Flask do not need `uvicorn`. + +See `runtime-and-entrypoints.md` for entrypoint discovery rules and conventional file names. + +Typical fixes: + +- Export `app` at top level. +- Do not rely on local dev commands such as `uvicorn main:app` as the deploy entrypoint. + +## Flask + +Minimal entrypoint: + +```python +from flask import Flask + +app = Flask(__name__) + + +@app.get("/") +def index(): + return "ok" +``` + +For non-trivial apps, Flask's [application factory](https://flask.palletsprojects.com/en/stable/tutorial/factory/) pattern is recommended. The factory function returns the app, and the top-level assignment makes it discoverable by Vercel: + +```python +from flask import Flask + + +def create_app(): + app = Flask(__name__) + # register blueprints, configure extensions + return app + + +app = create_app() +``` + +Flask is WSGI. It does not need `uvicorn` or any ASGI server dependency. + +Typical fixes: + +- Export `app` or `application` at top level. +- Declare `flask` in `pyproject.toml` or `requirements.txt`. +- Avoid debug-only local server code as the deployment path. + +## Django + +Django projects should have `manage.py` at the project root or one directory below. Vercel inspects settings and prefers `ASGI_APPLICATION` over `WSGI_APPLICATION`. + +Typical checks: + +```bash +python manage.py check +python manage.py collectstatic --noinput +``` + +If settings import fails locally, fix that before deploying. Common causes include missing dependencies, required environment variables, bad `ALLOWED_HOSTS`, or incorrect settings module paths. + +## Static Assets + +Use Vercel's `public/` directory for static files that do not need framework processing. + +FastAPI and Flask apps should not mount framework static directories for files that can live in `public/`. + +Django static collection can run during build when static settings are compatible. Supported patterns include: + +- Default Django static storage. +- `ManifestStaticFilesStorage`. +- WhiteNoise `CompressedManifestStaticFilesStorage`. +- `django-storages` configurations. + +`WHITENOISE_USE_FINDERS=True` can work without `STATIC_ROOT`, but prefer an explicit static setup for production. + +## Background Workers + +Vercel supports background task processing via the `vercel-workers` package. Worker services run alongside the web service and consume messages from Vercel Queues. + +The `vercel-workers` package provides: + +- `send()` and `@subscribe` primitives for publishing and consuming queue messages. +- Adapters for **Celery**, **Dramatiq**, and **Django tasks**. + +Worker services are configured in `vercel.json` using `experimentalServices`: + +```json +{ + "experimentalServices": { + "web": { + "framework": "fastapi", + "entrypoint": "main.py", + "routePrefix": "/" + }, + "worker": { + "type": "worker", + "entrypoint": "worker.py", + "topic": "default", + "consumer": "default" + } + } +} +``` + +When a Python app requires background processing (task queues, scheduled jobs, event-driven workers), check whether `vercel-workers` can handle the workload before concluding that the app is incompatible with Vercel. + +## Databases + +Vercel Marketplace provides managed database integrations that automatically configure connection environment variables: + +- **Neon Postgres** -- serverless PostgreSQL. +- **Supabase** -- PostgreSQL with auth, storage, and realtime. +- **AWS RDS** -- managed relational databases (PostgreSQL, MySQL). + +When a Python app requires a database, check whether a Vercel Marketplace integration can provision it. The integration sets connection environment variables (e.g., `DATABASE_URL`, `POSTGRES_URL`) automatically. + +## Environment Variables + +If app import requires secrets or database URLs, configure those in Vercel before deployment. Add environment variables via the Vercel dashboard, Vercel CLI, or by adding a Marketplace integration. + +Keep deployment diagnosis separate from secret handling: identify the missing variable name, then add it via the Vercel dashboard or CLI. diff --git a/skills/vercel-python/references/runtime-and-entrypoints.md b/skills/vercel-python/references/runtime-and-entrypoints.md new file mode 100644 index 00000000..46b562d2 --- /dev/null +++ b/skills/vercel-python/references/runtime-and-entrypoints.md @@ -0,0 +1,79 @@ +# Runtime and Entrypoints + +Use this reference when Vercel cannot find a Python app, the callable is wrong, routing behaves unexpectedly, or the project uses ASGI/WSGI directly. + +## Entrypoint Discovery + +Entrypoint resolution follows this priority: + +1. **`[tool.vercel].entrypoint`** in `pyproject.toml` — explicit path, highest priority. +2. **Framework-specific discovery:** + - **Django:** The builder reads `manage.py` to find `DJANGO_SETTINGS_MODULE`, then looks in the settings module for top-level symbols. + - **Everything else:** Conventional files named `app.py`, `index.py`, `server.py`, `main.py`, `wsgi.py`, or `asgi.py`. Search locations are the project root and shallow app directories such as `src`, `app`, and `api`. +3. **`[project.scripts].app`** in `pyproject.toml` — legacy fallback. + +Prefer `[tool.vercel].entrypoint` for new work: + +```toml +[tool.vercel] +entrypoint = "api/main.py" +``` + +## Callable Symbols + +For generic Python, FastAPI, and Flask apps, the entrypoint should expose one top-level callable: + +- `app` +- `application` +- `handler` + +Examples: + +```python +from fastapi import FastAPI + +app = FastAPI() +``` + +```python +from flask import Flask + +app = Flask(__name__) +``` + +If `handlerFunction` is configured in Vercel function settings, it must point to a top-level symbol. + +## ASGI and WSGI + +The runtime bridge distinguishes ASGI from WSGI by callable shape and async behavior. + +- FastAPI is ASGI. +- Flask is WSGI. +- Django can use ASGI or WSGI; prefer ASGI when `ASGI_APPLICATION` is configured. +- A `BaseHTTPRequestHandler` subclass is also supported. + +The runtime runs ASGI apps through a vendored Uvicorn layer for lifespan support. WSGI apps are adapted through HTTP request wrappers. + +## Django Discovery + +Django detection starts from `manage.py`, usually at the project root or one directory below. The builder reads `manage.py` to find the module used to set `DJANGO_SETTINGS_MODULE`, then looks in that module for top-level symbols. It prefers `ASGI_APPLICATION` over `WSGI_APPLICATION`. + +If the settings module depends on environment variables or other configuration, these must be set in the Vercel project so the build environment can resolve them. + +Common blockers: + +- `manage.py` is nested too deeply. +- `DJANGO_SETTINGS_MODULE` cannot import because dependencies or environment variables are missing. Set required env vars in the Vercel project settings. +- Settings only define `WSGI_APPLICATION` when the app expects ASGI behavior. + +## Working Directory + +At runtime, relative file reads such as `open("file.txt")` resolve from the project root. Use absolute paths based on `Path(__file__)` when code needs files next to a module. + +## Practical Fix Order + +1. Add or correct `[tool.vercel].entrypoint` for nonstandard layouts. +2. Ensure the entrypoint file exists inside the deployed project root. +3. Expose `app`, `application`, or `handler` at top level. +4. For Django, ensure `manage.py` and settings import locally before deploying. +5. Re-run the inspector before deploying. diff --git a/skills/vercel-python/references/sdk-runtime-apis.md b/skills/vercel-python/references/sdk-runtime-apis.md new file mode 100644 index 00000000..d3670db5 --- /dev/null +++ b/skills/vercel-python/references/sdk-runtime-apis.md @@ -0,0 +1,27 @@ +# Python SDK + +The official Python SDK for Vercel is the `vercel` package on PyPI. Do not use unofficial third-party packages for Vercel platform APIs. + +The SDK requires Python 3.10+ and provides both synchronous and asynchronous APIs. It is under active development and its API surface may change significantly between releases — concrete code examples are intentionally omitted here to avoid going stale. Refer to the [SDK README](https://github.com/vercel/vercel-py) for the latest code examples and the [vercel package on PyPI](https://pypi.org/project/vercel/) for release history. + +## Capabilities + +The SDK provides Python clients for the following Vercel platform features: + +- **Blob Storage** -- file upload, download, listing, and deletion. Requires a `BLOB_READ_WRITE_TOKEN` environment variable. +- **OIDC** -- Vercel identity tokens for authenticating with third-party services. +- **Runtime Cache** -- key-value cache with TTL and tag-based invalidation. +- **Cron Scheduling** -- schedule decorators detected by the Vercel builder at build time. +- **Workflow** -- durable multi-step orchestration with steps, sleep, and hooks. +- **Sandbox** -- remote compute environments for running code. +- **Projects and Deployments** -- platform API clients for project and deployment management. +- **Background Workers** -- queue message publishing and consumption, with adapters for Celery, Dramatiq, and Django tasks. Provided by the `vercel-workers` package. +- **Request Helpers** -- geolocation, client IP address, and Vercel environment variable access from within deployed functions. + +## Middleware Pattern + +Python web frameworks (FastAPI, Flask, Django) can call the SDK's `set_headers()` function at the start of each request to store Vercel-provided headers in a context variable. This enables OIDC token resolution and request helper functions to access Vercel headers without passing the request object explicitly. See the [SDK README](https://github.com/vercel/vercel-py) for the current middleware integration pattern. + +## Import Guidance + +Always use the `vercel` package for Vercel platform APIs. If code imports from an unofficial package, replace it with the official SDK. Refer to the [SDK README](https://github.com/vercel/vercel-py) for current import paths and examples. diff --git a/skills/vercel-python/references/troubleshooting.md b/skills/vercel-python/references/troubleshooting.md new file mode 100644 index 00000000..1c843ad7 --- /dev/null +++ b/skills/vercel-python/references/troubleshooting.md @@ -0,0 +1,109 @@ +# Troubleshooting + +Use this reference when Vercel build output, runtime logs, or the inspector reports a Python-specific diagnostic. + +## Entrypoint Diagnostics + +`PYTHON_ENTRYPOINT_NOT_FOUND` + +- Add a conventional entrypoint such as `app.py`, `main.py`, `server.py`, `wsgi.py`, or `asgi.py`. +- Or add `[tool.vercel].entrypoint = "path/to/file.py"` to `pyproject.toml`. + +`FASTAPI_ENTRYPOINT_NOT_FOUND` or `FLASK_ENTRYPOINT_NOT_FOUND` + +- Confirm the dependency is declared. +- Confirm the entrypoint file is inside the Vercel project root. +- Export a top-level `app`, `application`, or `handler`. + +`DJANGO_ENTRYPOINT_NOT_FOUND` + +- Confirm `manage.py` is at the project root or one directory below. +- Verify the settings module defines `ASGI_APPLICATION` or `WSGI_APPLICATION`: + ```bash + uv run manage.py diffsettings | grep -E 'WSGI_APPLICATION|ASGI_APPLICATION' + ``` +- Ensure required environment variables are set in the Vercel project so the settings module can import. + +`PYTHON_HANDLER_NOT_FOUND` + +- The entrypoint exists but no supported top-level callable was found. +- Export `app`, `application`, or `handler`. +- If a custom handler is configured, the target must be top-level. + +## Config Diagnostics + +`PYTHON_CONFIG_PARSE_ERROR` + +- Fix invalid TOML or JSON in Python/Vercel configuration. + +`PYTHON_CONFIG_VALIDATION_ERROR` + +- Check `[tool.vercel]` keys and Vercel function config. +- Prefer simple `[tool.vercel].entrypoint` for entrypoint overrides. + +`INVALID_VERCEL_JSON` + +- Fix invalid JSON in `vercel.json`. +- Remove comments; JSON does not allow them. + +## Dependency Diagnostics + +`PYTHON_REQUIREMENTS_PARSE_ERROR` + +- Remove unsupported pip options from requirements files. +- Check malformed requirement specifiers. +- Prefer `pyproject.toml` for new projects. + +`PYTHON_PIPFILE_LOCK_PARSE_ERROR` + +- Regenerate `Pipfile.lock`. +- If the project has moved to `pyproject.toml`, remove stale Pipfile artifacts. + +`PYTHON_DEPENDENCY_SYNC_FAILED` + +- Reproduce locally with `uv sync` or `uv pip install -r requirements.txt`. +- Check selected Python version compatibility. +- Check native dependencies that may lack Linux wheels. +- Remove conflicting manifests and stale lockfiles. + +## Python Version Diagnostics + +`BUILD_UTILS_PYTHON_VERSION_DISCONTINUED` + +- Move to Python 3.12, 3.13, or 3.14. +- Update `.python-version` or `project.requires-python`. + +Unsupported future versions: + +- Do not request Python versions newer than Vercel supports. +- Use a bounded range such as `>=3.12,<3.15`. + +## Django Diagnostics + +`DJANGO_SETTINGS_FAILED` + +- Run `python manage.py check` locally. +- Ensure required environment variables are available. +- Confirm settings paths, installed apps, middleware, and storage backends import correctly. +- Add missing environment variables via the Vercel dashboard or the Vercel CLI. + +## Size and Runtime Install Diagnostics + +`LAMBDA_SIZE_EXCEEDED` + +Vercel Python functions support up to 500 MB. When the bundle exceeds the standard limit and a `uv.lock` is present, the builder can automatically externalize public PyPI packages and install them at cold start. This is the primary fix path for large dependency sets. + +- Prefer `pyproject.toml` with `uv.lock` so the builder can externalize large public packages. +- Avoid custom install/build commands -- these disable the externalization optimization. +- Remove committed virtualenvs, caches, model files, generated artifacts, and unused heavy packages. +- Add targeted `excludeFiles` only for files safe to omit. + +Runtime dependency installation failure: + +- Check dependency compatibility with the selected Python version. +- Ensure the lockfile matches the manifest. +- Reduce dependency footprint before retrying. + +## Deployment Flow + +After Python issues are fixed, proceed with deployment. Use the Vercel CLI or a deployment skill if available for auth, domains, environment variables, and logs.