Skip to content

Troubleshooting & FAQ

Common questions and issues when working with Django Ninja AIO.

Relations & Serialization

My reverse FK / M2M fields return empty lists

Django Ninja AIO uses prefetch_related automatically for reverse relations, but it requires:

  1. The related field name must be in your ReadSerializer.fields
  2. The related model must also be a ModelSerializer (or have a schema defined)
Python
class Author(ModelSerializer):
    name = models.CharField(max_length=200)

    class ReadSerializer:
        fields = ["id", "name", "books"]  # "books" = related_name on Book.author

If books is not the correct related_name, check your ForeignKey definition:

Python
class Book(ModelSerializer):
    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name="books")
I get 'SynchronousOnlyOperation' errors with relations

This happens when Django's ORM is accessed synchronously inside an async context. Django Ninja AIO handles this automatically through prefetch_related and async iteration, but if you're writing custom code:

Python
# Wrong - synchronous access in async view
async def my_view(request):
    author = await Author.objects.aget(pk=1)
    books = author.books.all()  # SynchronousOnlyOperation!

# Correct - use async iteration
async def my_view(request):
    author = await Author.objects.prefetch_related("books").aget(pk=1)
    books = [book async for book in author.books.all()]

Tip

Let Django Ninja AIO handle relation serialization through ReadSerializer — it manages the async complexity for you.

Nested relations only show IDs, not full objects

Make sure the related model is also a ModelSerializer with its own ReadSerializer:

Python
# This will serialize books as full objects
class Book(ModelSerializer):
    title = models.CharField(max_length=200)

    class ReadSerializer:
        fields = ["id", "title"]  # This is required!

class Author(ModelSerializer):
    name = models.CharField(max_length=200)

    class ReadSerializer:
        fields = ["id", "name", "books"]

If Book doesn't have a ReadSerializer, the framework can't know how to serialize it.

Configuration & Setup

How do I disable specific CRUD operations?

Use the disable attribute on your ViewSet:

Python
@api.viewset(Book)
class BookViewSet(APIViewSet):
    disable = ["update", "delete"]  # Read-only API

Available operations: "create", "list", "retrieve", "update", "delete"

How do I use a different primary key type (UUID, etc.)?

Django Ninja AIO automatically infers the PK type from your model:

Python
import uuid
from django.db import models

class Article(ModelSerializer):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    title = models.CharField(max_length=200)

    class ReadSerializer:
        fields = ["id", "title"]

The generated endpoints will use UUID in the path schema automatically.

How do I change the pagination page size?

Override the pagination class on your ViewSet:

Python
from ninja.pagination import PageNumberPagination

class LargePagination(PageNumberPagination):
    page_size = 50
    max_page_size = 200

@api.viewset(Book)
class BookViewSet(APIViewSet):
    pagination_class = LargePagination

Authentication

How do I make some endpoints public and others protected?

Use per-method auth attributes:

Python
@api.viewset(Book)
class BookViewSet(APIViewSet):
    auth = [JWTAuth()]      # Default: all endpoints require auth
    get_auth = None          # GET endpoints (list, retrieve) are public

Available per-method attributes: get_auth, post_auth, put_auth, patch_auth, delete_auth

I get 401 errors even with a valid token

Check these common causes:

  1. Token format — Ensure the header is Authorization: Bearer <token> (not Token or JWT)
  2. Key mismatch — Verify your public key matches the key used to sign tokens
  3. Algorithm — Make sure jwt_alg matches the signing algorithm (e.g., RS256, HS256)
  4. Claims — Check required claims are present in the token payload

Database & Queries

How do I optimize queries for large datasets?

Use QuerySet configuration on your model:

Python
class Article(ModelSerializer):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE)

    class ReadSerializer:
        fields = ["id", "title", "author"]

    class QuerySet:
        read = {
            "select_related": ["author"],
            "prefetch_related": ["tags"],
        }

This ensures select_related and prefetch_related are applied automatically.

Filtering is slow on large tables

  1. Add database indexes to frequently filtered fields:

    Python
    class Article(ModelSerializer):
    title = models.CharField(max_length=200, db_index=True)
    is_published = models.BooleanField(default=False, db_index=True)

  2. Keep pagination enabled — never return unbounded querysets

  3. Limit slices for search-heavy endpoints: queryset = queryset[:1000]

Common Errors

ImportError: cannot import name 'ModelSerializer'

Make sure you're importing from the correct module:

Python
# Correct
from ninja_aio.models import ModelSerializer

# Wrong
from ninja_aio import ModelSerializer
AttributeError: type object 'MyModel' has no attribute 'generate_read_s'

Your model must inherit from ModelSerializer, not Django's models.Model:

Python
# Correct
from ninja_aio.models import ModelSerializer

class MyModel(ModelSerializer):
    ...

# Wrong
from django.db import models

class MyModel(models.Model):
    ...

If you can't change the base class, use the Meta-driven Serializer instead.

Circular import errors between models

Use string references for ForeignKey relations to models in other files:

Python
class Book(ModelSerializer):
    author = models.ForeignKey("myapp.Author", on_delete=models.CASCADE)

For serializer references, Django Ninja AIO supports string-based relation resolution.

Still Stuck?