Error Loading ASGI App: Could Not Import Module "main" — Causes and Fixes (Complete Guide)

 When running a FastAPI or ASGI-based application with Uvicorn or Gunicorn, you may encounter the following error:

Error loading ASGI app. Could not import module "main".

This error indicates that the ASGI server cannot locate or import the Python module specified in your startup command. Below is a structured, technical guide to diagnose and resolve this issue efficiently.

---

What Does “Could Not Import Module 'main'” Mean?

In ASGI applications (e.g., FastAPI), you typically start your server with a command like:

uvicorn main:app --reload

This command tells Uvicorn to:

• Import a Python file named main.py

• Locate an ASGI instance called app

• Run the application

If Python cannot resolve main as a module, the server throws:

Error loading ASGI app. Could not import module "main"

---

Common Causes and How to Fix Them

1️⃣ Incorrect File Name

Problem

Your file is not actually named main.py.

Example:

app.py
server.py
application.py

Fix

Update your command to match the actual filename:

uvicorn app:app --reload

Structure rule:

uvicorn <filename_without_py>:<ASGI_variable>

---

2️⃣ Wrong Working Directory

Problem

You are running the command from the wrong directory.

Example project structure:

project/
│
├── app/
│   ├── main.py
│

If you are in project/ and run:

uvicorn main:app --reload

It will fail because main.py is inside app/.

Fix Option A: Change directory

cd app
uvicorn main:app --reload

Fix Option B: Use module path

uvicorn app.main:app --reload

---

3️⃣ Missing __init__.py in a Package

If you're using a package structure:

project/
│
├── app/
│   ├── __init__.py
│   ├── main.py

Without __init__.py, Python may not treat app as a module (depending on environment and version).

Fix

Create an empty file:

touch app/__init__.py

---

4️⃣ Virtual Environment Not Activated

If dependencies are installed in a virtual environment but it’s not activated, Python may fail during import.

This can indirectly produce module import errors.

Fix

Activate your virtual environment:

macOS/Linux

source venv/bin/activate

Windows

venv\Scripts\activate

Then run:

uvicorn main:app --reload

---

5️⃣ Import Errors Inside main.py

Sometimes the real issue is not main, but something imported inside it.

Example:

from database import connect

If database.py is missing or mislocated, Python fails to import main entirely.

How to Debug

Run:

python main.py

If there is an internal import error, Python will show the exact traceback.

---

6️⃣ Incorrect ASGI Variable Name

Your file may not define app.

Example:

application = FastAPI()

But you run:

uvicorn main:app --reload

Fix

Either rename the variable:

app = FastAPI()

Or update the command:

uvicorn main:application --reload

---

7️⃣ PYTHONPATH Issues (Advanced Case)

If running from Docker, CI/CD, or a production server, the Python path may not include your project root.

You may see this especially when deploying with:

• Gunicorn

• Docker containers

• Kubernetes

Fix

Explicitly define the app directory:

uvicorn main:app --app-dir .

Or export PYTHONPATH:

export PYTHONPATH=$PWD

---

Example: Correct FastAPI Setup

With FastAPI, a minimal working example:

Project Structure

project/
│
├── main.py

main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

Run

uvicorn main:app --reload

If everything is correct, the server will start successfully.

---

Quick Troubleshooting Checklist

Before searching further, verify:

• ✔ The file name matches the command

• ✔ You are in the correct directory

• ✔ The ASGI variable name is correct

• ✔ No internal import errors exist

• ✔ Virtual environment is activated

• ✔ __init__.py exists if using packages

---

Special Case: Running with Gunicorn

When using:

gunicorn main:app -k uvicorn.workers.UvicornWorker

Ensure:

• The module path is correct

• The working directory is correct

• Dependencies are installed in the environment

---

Summary

The error:

Error loading ASGI app. Could not import module "main"

is not a runtime crash — it is a module resolution issue.

In most cases, the root cause is:

• Wrong filename

• Wrong directory

• Incorrect import path

• Internal Python import failure

Once you systematically verify these factors, the issue can typically be resolved within minutes.