# Fix You Must Pass the Application as an Import String to Enable Reload in Uvicorn

Yes. An agent shows the process exiting right after the warning, switches uvicorn.run to the import string the project's CLI uses, proves reload works, opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/fix-you-must-pass-the-application-as-an-import-string/uvicorn/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads every way the server is started. In a FastAPI project like StacklokLabs/mockllm, the root `main.py` imports `app` from `src.mockllm.server` and calls `uvicorn.run(app, host="0.0.0.0", port=8000, reload=True)`, passing the application object. Two other entry points in the same repository already do it the other way: `src/mockllm/__main__.py` calls `uvicorn.run("mockllm.server:app", host="0.0.0.0", port=8000, reload=True)`, and `src/mockllm/cli.py` defines a Click command with `--reload` defaulting to true that calls `uvicorn.run("mockllm.server:app", host=host, port=port, reload=reload)`, exposed as the `mockllm` script in `pyproject.toml`. The project depends on `fastapi>=0.68.0` and `uvicorn>=0.15.0` through Poetry, loads its answers from a `responses.yml` that `example.responses.yml` provides, and ships a `Makefile` and `pytest.ini`.

Then it reproduces the failure, which is not just a warning. With a fresh install resolving Uvicorn 0.54.0 and FastAPI 0.162.2, `python main.py` logs that it loaded the four example responses, prints `WARNING:  You must pass the application as an import string to enable 'reload' or 'workers'.` and exits with status 3; nothing listens on port 8000, `GET /health` gets no answer, and the process has no child. The reason is in `uvicorn/main.py`: when `reload` or `workers` is set and `app` is not a string, `run` logs that line and calls `sys.exit(STARTUP_FAILURE)`, because the reloader has to spawn a worker that imports the application by name. The same line prints on 0.13.3, 0.15.0, 0.20.0 and 0.30.1.

The fix is the one the repository's own CLI already made: `main.py` passes `"src.mockllm.server:app"` as a string, with the same host, port and `reload=True`. Run that way, the parent process starts a reloader with two child processes, `GET /docs` answers `200`, and touching `src/mockllm/models.py` keeps the server up while the worker restarts. The import string is relative to the directory `python main.py` runs from, which is why the root script names `src.mockllm.server` where the packaged CLI names `mockllm.server`.

The agent then checks the `responses.yml` requirement the three entry points share, since `python -m mockllm` from the `src` directory fails to find the file in the working directory, and writes the pull request so the owner can see the choice between keeping `main.py` as a thin wrapper that matches the CLI or deleting it in favour of `mockllm --reload`. It changes no handler code and does not touch the Click command.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Running this FastAPI project with `python main.py` prints \"You must pass the application as an import string to enable 'reload' or 'workers'\" and does not serve. Read pyproject.toml, main.py and every other place that calls uvicorn.run first, and note which ones pass an import string. Install the dependencies, run the script, quote the warning and the exit status, and show that nothing listens on the port. Find the line in uvicorn that produces the warning and say what it does after printing it. Change the script to pass the application as an import string with the same host, port and reload setting, run it again, show the port answers and that a file change restarts the worker, and say whether the script should stay or defer to the project's own CLI. Do not change any route or the CLI. Open a pull request that quotes the failing and passing runs.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request touching `main.py` only: the application object replaced by the `"src.mockllm.server:app"` string on the `uvicorn.run` line, everything else in the file unchanged. The description quotes the warning with the exit status from the failing run and the `uvicorn/main.py` lines that print it and exit, then the passing run: the reloader's two child processes, the `200` from `/docs`, and the worker restart after a file was touched. It names `src/mockllm/__main__.py` and `cli.py` as the entry points that already used the string form, and offers deleting `main.py` as an alternative.

A reviewer checks that the host, port and reload flag match the original call, that the import string resolves from the directory the README runs the script in, and that no other `uvicorn.run` call in the repository passes an object with `reload` or `workers` set. The run's record holds both starts with their full output, so the exit and the restart can be read rather than taken on trust.

## Run it on every Linear issue labelled dev-server

Add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled` with the label `dev-server`. The trigger appends the labelled issue after the prompt, so a report that says `python main.py` prints a warning and exits reaches the agent with its own words, and one run opens one pull request on its own branch that links the issue. A labelled issue that describes something else ends with a one-line answer rather than a change.

From your own code, send this body to `POST /o/{org}/sessions` with an API key, the repository in `resources` and a `request_id` that is a UUID v5 of the issue id, so a second label event for the same issue returns the run already started. The key's `webhook_url` receives `run.completed` with `data.session_url` when the pull request is up.

## Why run it on Rush?

A warning that is really an exit is easy to misread on a laptop, where a terminal shows the line and the developer assumes the server is up. The agent's sandbox makes the state plain: it reads the exit status, probes the port, counts the processes, and keeps every command and its output in the run's record, so the pull request says the script never served rather than that it printed something.

A repository with three entry points also needs someone to read all three before changing one. The agent finds the two that already pass an import string, makes the third match them, and puts the alternative, dropping the script for the CLI, in front of the owner as a decision rather than making it silently.

## Frequently asked questions

### Why does Uvicorn need a string for reload?

The reloader runs the application in a separate worker process, and a worker started that way cannot be handed a Python object from the parent; it imports the application by module and attribute name instead. The same applies to `workers` greater than one. Without the string, Uvicorn logs the line and exits with its startup-failure status, 3 on 0.54.0.

### Does the import string depend on where I run the script?

Yes. Uvicorn imports it the way `import` would, from the current directory and `sys.path`, so a root script in this repository names `src.mockllm.server:app`, while the packaged CLI names `mockllm.server:app` because the package is installed. The pull request says which directory the script expects, which is the one the README uses.

### Could the fix just drop reload=True?

That makes `python main.py` serve without a reloader, which is fine for a container but not for the development loop the flag was there for. The pull request keeps the flag and fixes the call; if you want a production entry point without reload, say so and the agent writes that as a second script instead.

### Why mention responses.yml at all?

Every entry point loads it from the working directory, and the sandbox run showed `python -m mockllm` from `src` failing on that file before Uvicorn ran. The agent reports it so the reviewer knows the reload fix was proven with the example file copied into place, and that the file lookup is a separate matter.

## More jobs like this: Turn a Linear label into a PR

- [Turn Labeled GitHub Issues Into Pull Requests for an Ansible Role](https://getrush.ai/run/github-issue-to-pr/ansible/)
- [Turn Labeled GitHub Issues Into Pull Requests for a Django App](https://getrush.ai/run/github-issue-to-pr/django/)
- [Turn Labeled GitHub Issues Into Pull Requests for an Express API](https://getrush.ai/run/github-issue-to-pr/express/)
- [Turn Labeled GitHub Issues Into Pull Requests for a FastAPI App](https://getrush.ai/run/github-issue-to-pr/fastapi/)
- [Turn GitHub Issues into Pull Requests for a Fastify API](https://getrush.ai/run/github-issue-to-pr/fastify/)
- [Turn GitHub Issues into Pull Requests for a Go Project](https://getrush.ai/run/github-issue-to-pr/go/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
