Development

Troubleshooting

Common issues and solutions for ZineCore2

This guide covers common issues you may encounter when developing with or deploying ZineCore2, along with solutions.

Installation Issues

"Python 3.12 or higher required"

Problem: System Python is too old.

Solution:

# macOS with Homebrew
brew install [email protected]

# Ubuntu/Debian
sudo apt install python3.12 python3.12-venv

# Or use pyenv
pyenv install 3.12.1
pyenv local 3.12.1

"uv: command not found"

Problem: uv not installed or not in PATH.

Solution:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to PATH
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify
uv --version

"git submodule update --init" fails

Problem: Spec submodule not configured.

Solution:

# Initialize submodules
cd /path/to/server
git submodule update --init

# If still fails, try:
git submodule sync
git submodule update --init --recursive

Database Issues

"could not connect to server: Connection refused"

Problem: PostgreSQL not running.

Solution:

# macOS (Homebrew)
brew services start postgresql@16

# Ubuntu/Debian
sudo systemctl start postgresql

# Check status
pg_isready

"FATAL: password authentication failed"

Problem: Incorrect database credentials.

Solution:

Check .env file:

cat backend/.env

Ensure DATABASE_URL matches PostgreSQL credentials:

DATABASE_URL=postgresql://USERNAME:PASSWORD@HOST:PORT/DATABASE

Test connection:

psql -U zinecore2 -h localhost -p 5433 -d zinecore2
# Enter password when prompted

"database "zinecore2" does not exist"

Problem: Database not created.

Solution:

# Create database
createdb zinecore2

# Or via psql
psql -U postgres
CREATE DATABASE zinecore2;
\q

"relation "catalog_zine" does not exist"

Problem: Migrations not run.

Solution:

cd backend
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  ../.venv/bin/python manage.py migrate

Migration Issues

"Migration is being applied before its dependency"

Problem: Incorrect migration dependencies.

Solution:

Edit migration file and fix dependencies:

# catalog/migrations/0004_fix.py
class Migration(migrations.Migration):
    dependencies = [
        ('catalog', '0003_previous_migration'),  # Ensure this is correct
    ]

"Column already exists"

Problem: Database already has the column.

Solution:

Fake the migration:

python manage.py migrate catalog 0004 --fake

Warning: Only use --fake if you're certain the database is already correct.

"Cannot drop table: still referenced by foreign key"

Problem: Foreign key constraints prevent deletion.

Solution:

Create migration to remove foreign keys first:

operations = [
    migrations.RemoveField(
        model_name='holding',
        name='zine',
    ),
    migrations.DeleteModel(
        name='Zine',
    ),
]

API Issues

"401 Unauthorized"

Problem: Missing or invalid authentication token.

Solution:

Get token:

curl -X POST http://localhost:8000/api/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "yourpassword"}'

Use token in requests:

curl -X POST http://localhost:8000/api/zines/ \
  -H "Authorization: Token YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{...}'

"400 Bad Request: This field is required"

Problem: Missing required field.

Solution:

Check required fields for the endpoint:

Zines:

zine_id, title, creator, subject, genre, date, language, rights

Agents:

agent_id, kind, display_name, public

Holdings:

holding_id, zine_id, repository_id

Repositories:

repo_id, repository_name, repository_kind, country

"400 Bad Request: Agent 'agent_xxx' does not exist"

Problem: Referenced agent doesn't exist.

Solution:

Create agent first:

curl -X POST http://localhost:8000/api/agents/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_xxx",
    "kind": "Person",
    "display_name": "Name",
    "public": true
  }'

Then create zine referencing the agent.

"404 Not Found"

Problem: Resource doesn't exist or wrong URL.

Solution:

Check URL:

# Correct
curl http://localhost:8000/api/zines/zine_001/

# Wrong (missing trailing slash)
curl http://localhost:8000/api/zines/zine_001

# Wrong (using internal ID instead of external ID)
curl http://localhost:8000/api/zines/123/

Server Issues

"ModuleNotFoundError: No module named 'zinecore'"

Problem: Not in correct directory or environment not activated.

Solution:

# Activate virtual environment
source .venv/bin/activate

# Ensure in backend/ directory
cd backend

# Run server
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  python manage.py runserver

"ImproperlyConfigured: Set the SECRET_KEY environment variable"

Problem: SECRET_KEY not set.

Solution:

Generate secret key:

python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

Add to .env:

# backend/.env
SECRET_KEY=your-generated-secret-key-here

"DisallowedHost at / Invalid HTTP_HOST header"

Problem: Hostname not in ALLOWED_HOSTS.

Solution:

Add to .env:

ALLOWED_HOSTS=localhost,127.0.0.1,yourdomain.com

Or for development:

ALLOWED_HOSTS=*

"Port 8000 already in use"

Problem: Another process using port 8000.

Solution:

Find and kill process:

# macOS/Linux
lsof -ti:8000 | xargs kill -9

# Or use different port
python manage.py runserver 8001

Performance Issues

"API responses are slow"

Problem: N+1 query problem or missing indexes.

Solution:

Use select_related/prefetch_related:

# catalog/views.py
class ZineViewSet(viewsets.ModelViewSet):
    def get_queryset(self):
        return Zine.objects.prefetch_related(
            'creator_agents',
            'subject_objects'
        )

Add database indexes:

Check if frequently queried fields are indexed:

class Zine(models.Model):
    zine_id = models.CharField(db_index=True)  # Indexed
    title = models.CharField()  # Not indexed

Enable query logging (development):

# settings/development.py
LOGGING = {
    'loggers': {
        'django.db.backends': {
            'level': 'DEBUG',
        }
    }
}

"Database queries are slow"

Problem: Missing indexes or inefficient queries.

Solution:

Check EXPLAIN:

EXPLAIN ANALYZE SELECT * FROM catalog_zine WHERE title LIKE '%feminism%';

Add indexes:

class Zine(models.Model):
    class Meta:
        indexes = [
            models.Index(fields=['title']),
            models.Index(fields=['created_at']),
        ]

Optimize ArrayField queries:

# Use GIN index for array contains queries
zines = Zine.objects.filter(subject__contains=['feminism'])

Testing Issues

"Tests fail: database access not allowed"

Problem: Test trying to access database without TestCase.

Solution:

Use TestCase instead of SimpleTestCase:

# Bad
from django.test import SimpleTestCase

class MyTest(SimpleTestCase):  # Can't access database
    pass

# Good
from django.test import TestCase

class MyTest(TestCase):  # Can access database
    pass

"Tests are very slow"

Problem: Creating database for each test run.

Solution:

Use --keepdb:

python manage.py test --keepdb

Or configure in settings:

# settings/testing.py
TEST_RUNNER = 'django.test.runner.DiscoverRunner'
TEST_KEEP_DB = True

"ImportError in tests"

Problem: Test files not following naming convention.

Solution:

Ensure test files start with test_:

tests/
├── test_models.py     # ✓ Discovered
├── test_views.py      # ✓ Discovered
├── models_test.py     # ✗ Not discovered
└── utils.py           # ✗ Not a test file

Production Deployment Issues

"502 Bad Gateway"

Problem: nginx can't connect to gunicorn.

Solution:

Check gunicorn status:

sudo systemctl status zinecore2.service

Check if gunicorn is listening:

sudo netstat -tlnp | grep 8000

Check logs:

sudo journalctl -u zinecore2.service -n 50

"Static files not loading"

Problem: Static files not collected or nginx misconfigured.

Solution:

Collect static files:

cd backend
DJANGO_SETTINGS_MODULE=zinecore.settings.production \
  python manage.py collectstatic --noinput

Check nginx config:

location /static/ {
    alias /opt/zinecore2/server/staticfiles/;
}

Verify permissions:

ls -la /opt/zinecore2/server/staticfiles/
# Should be readable by nginx user

"SSL certificate errors"

Problem: Let's Encrypt certificate expired or not configured.

Solution:

Renew certificate:

sudo certbot renew

Check expiration:

sudo certbot certificates

Auto-renewal:

Ensure certbot timer is enabled:

sudo systemctl status certbot.timer

CORS Issues

"CORS error in browser"

Problem: CORS not configured for frontend domain.

Solution:

Add to .env:

CORS_ALLOWED_ORIGINS=https://yourfrontend.com,https://www.yourfrontend.com

Or for development:

CORS_ALLOW_ALL_ORIGINS=True

Restart server after changing.

Vocabulary Issues

"Invalid subject codes: xxx"

Problem: Vocabulary not loaded or code doesn't exist.

Solution:

Load vocabularies:

cd backend
DJANGO_SETTINGS_MODULE=zinecore.settings.development \
  python manage.py load_vocabularies

Check available codes:

curl http://localhost:8000/api/vocabularies/subjects/ | jq '.[].code'

"Vocabularies not loading"

Problem: Spec submodule not initialized.

Solution:

cd /path/to/server
git submodule update --init

# Then load vocabularies
cd backend
python manage.py load_vocabularies

Debugging Tips

# settings/development.py
INSTALLED_APPS += ['debug_toolbar']
MIDDLEWARE += ['debug_toolbar.middleware.DebugToolbarMiddleware']
INTERNAL_IPS = ['127.0.0.1']

pip install django-debug-toolbar

Check Django Settings

python manage.py diffsettings

Shows which settings differ from defaults.

Run System Checks

python manage.py check
python manage.py check --deploy  # Production checks

View Database Schema

python manage.py dbshell

\d catalog_zine
\d+ catalog_zine  -- With more details

Django Shell

python manage.py shell

from catalog.models import Zine
Zine.objects.count()
Zine.objects.first()

View Logs

Development:

# Django dev server prints to console
python manage.py runserver

Production:

# Application logs
sudo tail -f /var/log/zinecore2/gunicorn-error.log

# nginx logs
sudo tail -f /var/log/nginx/zinecore2-error.log

# systemd logs
sudo journalctl -u zinecore2.service -f

Getting More Help

Check Documentation

Search Issues

GitHub Issues
Search closed issues (may be fixed)

Ask for Help

GitHub Discussions — General questions
GitHub Issues — Bug reports
Community Chat — Real-time help

When asking:

Include error messages
Include steps to reproduce
Include environment details
Share relevant code/config (without secrets!)

Common Error Messages

Error	Likely Cause	Solution
ModuleNotFoundError	Wrong directory or venv not activated	Activate venv, cd to correct dir
OperationalError: no such table	Migrations not run	Run python manage.py migrate
ImproperlyConfigured	Missing setting	Check .env file
401 Unauthorized	Missing/invalid token	Get new token
400 Bad Request	Invalid data	Check required fields
404 Not Found	Wrong URL or ID	Check endpoint/ID
500 Internal Server Error	Application error	Check logs
502 Bad Gateway	gunicorn not running	Check service status
CORS error	CORS not configured	Add origin to CORS settings

Still having issues? Check GitHub Issues or ask in community channels.

Edit this pageorReport an issue

Code Style

Coding standards and best practices for ZineCore2

Tutorials

Hands-on guides for learning ZineCore2