Troubleshooting

Common issues and solutions when using Django Client.

Generation Issues

No Operations Found

Problem:


✅ Generated 0 operations

Causes:

No ViewSets registered in URL router
drf-spectacular not properly configured
Apps not included in group configuration

Solutions:

1. Check ViewSets are registered:


# users/api/views.py
from rest_framework import viewsets
 
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

2. Verify URL patterns:


# users/urls.py
from rest_framework.routers import DefaultRouter
 
router = DefaultRouter()
router.register('users', UserViewSet)
urlpatterns = router.urls

3. Check Django-CFG configuration:


groups=[
    OpenAPIGroupConfig(
        name="core",
        apps=["users"],  # ✅ Make sure app is included
    ),
]

4. Validate OpenAPI schema:


python manage.py spectacular --validate --format openapi --file openapi.yaml

Empty Generated Files

Problem: Generated client has no models or operations.

Solution:

Check OpenAPI schema has content:


# Generate schema
python manage.py spectacular --file openapi.yaml
 
# Check file size
ls -lh openapi.yaml
 
# View content
cat openapi.yaml

If schema is empty:

Ensure drf-spectacular is in INSTALLED_APPS
Check REST_FRAMEWORK has DEFAULT_SCHEMA_CLASS
Verify ViewSets have serializers

TypeScript Issues

Module Not Found

Problem:


Module 'zod' not found
Module 'swr' not found

Solution:

Install dependencies:


cd frontend
npm install zod swr
# or
pnpm install zod swr
# or
yarn add zod swr

Type Errors

Problem:


error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'

Solutions:

1. Regenerate with latest version:


pip install --upgrade django-cfg
python manage.py generate_api

2. Check OpenAPI schema:

Ensure field types are correct in Django serializers:


# ❌ Wrong
class UserSerializer(serializers.Serializer):
    id = serializers.CharField()  # Should be IntegerField
 
# ✅ Correct
class UserSerializer(serializers.Serializer):
    id = serializers.IntegerField()

3. Clear TypeScript cache:


cd frontend
rm -rf node_modules/.cache
rm -rf .next  # for Next.js
pnpm tsc --noEmit  # Check for errors

Import Errors

Problem:


Cannot find module '@/api/generated/users'

Solution:

1. Check tsconfig.json paths:


{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

2. Verify generated files exist:


ls -la src/api/generated

3. Restart TypeScript server:

In VS Code: Cmd+Shift+P → “TypeScript: Restart TS Server”

Python Issues

ModuleNotFoundError

Problem:


ModuleNotFoundError: No module named 'api_client'

Solutions:

1. Add to Python path:


import sys
sys.path.insert(0, '/path/to/api_client')
 
from api_client import APIClient

2. Install as editable package:


cd api_client
pip install -e .

3. Check PYTHONPATH:


export PYTHONPATH="${PYTHONPATH}:/path/to/backend"
python -c "from api_client import APIClient"

ValidationError

Problem:


pydantic.error_wrappers.ValidationError: 1 validation error for User

Solutions:

1. Check request data matches schema:


# ❌ Wrong
await client.users.create(data={
    "id": 1,  # Read-only field!
    "username": "john"
})
 
# ✅ Correct
await client.users.create(data={
    "username": "john",
    "email": "[email protected]"
})

2. Use Pydantic models for validation:


from api_client.models import UserRequest
 
# Validate before sending
user_data = UserRequest.model_validate({
    "username": "john",
    "email": "[email protected]"
})
 
await client.users.create(data=user_data)

Runtime Issues

Authentication Not Working

Problem: API returns 401 Unauthorized.

Solutions:

TypeScript:


import { configureAPI } from '@/api/generated/api-instance'
 
configureAPI({
  baseUrl: 'https://api.example.com',
  getAuthToken: () => {
    // ✅ Get token from storage
    return localStorage.getItem('auth_token')
  },
})

Python:


client = APIClient(
    base_url="https://api.example.com",
    headers={
        "Authorization": f"Bearer {get_auth_token()}"
    }
)

CORS Errors

Problem:


Access to fetch at 'https://api.example.com' from origin 'http://localhost:3000'
has been blocked by CORS

Solution:

Configure CORS in Django:


# settings.py
INSTALLED_APPS += ['corsheaders']
 
MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware',  # ✅ Add this
    'django.middleware.common.CommonMiddleware',
    ...
]
 
CORS_ALLOWED_ORIGINS = [
    "http://localhost:3000",
    "http://localhost:3001",
]
 
# ⚠️ Development only
CORS_ALLOW_ALL_ORIGINS = True  # Don't use in production!

File Upload Not Working

Problem:


TypeError: file is not a File or Blob

Solutions:

1. Browser (correct):


// ✅ Correct
const file = event.target.files[0]  // File object
await uploadDocument({ title: "Doc", file: file })
 
// ❌ Wrong
await uploadDocument({ title: "Doc", file: "path/to/file" })

2. React Native:


import { launchImageLibrary } from 'react-native-image-picker'
 
const result = await launchImageLibrary({ mediaType: 'photo' })
const file = {
  uri: result.assets[0].uri,
  type: result.assets[0].type,
  name: result.assets[0].fileName,
}
 
// Use FormData
const formData = new FormData()
formData.append('file', file)
await uploadDocument({ title: "Doc", file: formData })

Network Errors

Problem:


TypeError: Failed to fetch

Solutions:

1. Check API is running:


curl https://api.example.com/health

2. Check baseUrl configuration:


configureAPI({
  baseUrl: 'https://api.example.com',  // ✅ No trailing slash
})

3. Check network connectivity:


ping api.example.com

Configuration Issues

Schema Generation Fails

Problem:


CommandError: Error generating schema

Solutions:

1. Install drf-spectacular:


pip install drf-spectacular>=0.26.5

2. Configure Django settings:


INSTALLED_APPS = [
    'rest_framework',
    'drf_spectacular',
]
 
REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

3. Validate configuration:


python manage.py spectacular --validate

Rate Limiting Blocks Generation

Problem: Schema endpoints return 429 Too Many Requests.

Solution:

Exempt schema endpoints from rate limiting:


# Django-CFG configuration
RATE_LIMIT_EXEMPT_PATHS = [
    '/schema/',
    '/api/schema/',
]

Performance Issues

Slow Generation

Problem: Generation takes too long (>30 seconds).

Solutions:

1. Use groups to split APIs:


# Split into smaller groups
groups=[
    OpenAPIGroupConfig(name="core", apps=["users", "auth"]),
    OpenAPIGroupConfig(name="billing", apps=["payments"]),
]

2. Generate specific groups only:


# Only regenerate core
python manage.py generate_api --groups core

3. Check for circular imports:

Ensure no circular dependencies in Django models.

Large Bundle Size

Problem: Generated TypeScript client is too large.

Solutions:

1. Use groups to split code:


# Generate separate clients
groups=[
    OpenAPIGroupConfig(name="web", apps=["users", "content"]),
    OpenAPIGroupConfig(name="admin", apps=["admin", "analytics"]),
]

2. Import only what you need:


// ✅ Specific imports
import { getUsers } from '@/api/generated/core/_utils/fetchers/users'
 
// ❌ Import everything
import * as api from '@/api/generated/core'

Debugging Tips

Enable Verbose Logging


# Django-CFG debug mode
DJANGO_CFG_DEBUG=1 python manage.py generate_api

Check Generated Code

Inspect generated files:


# TypeScript
cat frontend/src/api/generated/client.ts
 
# Python
cat backend/api_client/client.py

Validate OpenAPI Schema


# Validate schema
python manage.py spectacular --validate
 
# Generate and view schema
python manage.py spectacular --file openapi.yaml
cat openapi.yaml

Test API Manually


# Test API endpoint
curl -X GET https://api.example.com/api/users/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Getting Help

If you encounter issues not covered here:

Check documentation: Overview, Examples
Search issues: GitHub Issues
Ask community: Discord
Report bug: Open a new issue with:
- Django-CFG version
- OpenAPI schema (if possible)
- Error messages
- Steps to reproduce

Next Steps

Examples - Usage examples
Advanced Topics - Groups, CI/CD
Overview - Feature overview