Skip to content

Troubleshooting Guide

Common issues and solutions when integrating Tenxyte.

Migrating to v0.9.3 (Core Re-architecture)

DeprecationWarning: Importing X from tenxyte.Y is deprecated

Symptom: Your console shows warnings when starting the server or running tests.

Cause: In v0.9.3, the project was restructured into a Core and Adapters architecture. Many internal Django services were refactored to use the framework-agnostic Core.

Fix: Update your imports. Instead of: 

from tenxyte.services.auth_service import AuthService
Use: 
from tenxyte.core.jwt_service import JWTService
(Note: The old imports will continue to work until v1.0.0).

Custom Adapters not being used

Symptom: You wrote a custom adapter (e.g., CacheService), but the system continues to use the default Django Cache.

Cause: Custom adapters need to be passed explicitly to the Core services (e.g., JWTService, TOTPService) that use them.

Fix: Follow the initialization steps detailed in the Custom Adapters Guide to ensure your custom adapter instances are passed into the Core services.

Installation & Settings

tenxyte.setup() has no effect

Symptom: INSTALLED_APPS, AUTH_USER_MODEL, or MIDDLEWARE are not being configured automatically.

Cause: tenxyte.setup() reads your existing INSTALLED_APPS, MIDDLEWARE, and other settings, then appends to them. It must be called at the very end of your settings.py (after all your Django settings are defined), otherwise it won't see them.

Fix: 

# settings.py — Add this at the END of the file (after INSTALLED_APPS, MIDDLEWARE, etc.)
import tenxyte
tenxyte.setup(globals())

Do not call it inside if TYPE_CHECKING: blocks or inside functions.

ImproperlyConfigured: TENXYTE_JWT_SECRET_KEY must be set in production

Cause: Running with DEBUG=False without a dedicated JWT secret.

Fix: 

# settings.py
TENXYTE_JWT_SECRET_KEY = 'your-strong-dedicated-jwt-secret'  # NOT Django's SECRET_KEY

Generate a secure key: 

python -c "import secrets; print(secrets.token_hex(64))"

Migrations fail with table tenxyte_user already exists

Cause: A previous partial migration or a conflicting AUTH_USER_MODEL.

Fix: 

python manage.py migrate tenxyte --fake-initial

If the issue persists, check that AUTH_USER_MODEL = 'tenxyte.User' is set before running the first migration.

Authentication & JWT

401 TOKEN_EXPIRED immediately after login

Symptom: The access token is accepted at login but rejected on the next request.

Cause: Server clock is out of sync, or TENXYTE_JWT_ACCESS_TOKEN_LIFETIME is set too low.

Fix: 

TENXYTE_JWT_ACCESS_TOKEN_LIFETIME = 900  # 15 minutes (in seconds)
Also ensure the server clock is synchronised (NTP).

401 TOKEN_BLACKLISTED after logout

Symptom: Token is rejected even though the user just logged in again.

Cause: The old token was blacklisted but the client is still sending it.

Fix: Ensure the client replaces the stored tokens with the new TokenPair received from the re-login response.

403 2FA_REQUIRED — user can't log in

Cause: 2FA is enabled on the account but the client isn't sending totp_code.

Fix: Include the TOTP code in the login request body: 

{
  "email": "user@example.com",
  "password": "...",
  "totp_code": "123456"
}

If the user has lost access to their authenticator app, they must use a backup code.

Rate Limiting

All requests return 429 in tests

Cause: Rate limiting is active and the test runner shares a cache key.

Fix: Disable throttling for tests: 

# tests/settings.py
REST_FRAMEWORK = {
    **REST_FRAMEWORK,
    'DEFAULT_THROTTLE_CLASSES': [],
}

Or mock it per-test: 

from unittest.mock import patch

with patch('rest_framework.throttling.SimpleRateThrottle.allow_request', return_value=True):
    response = client.post('/api/v1/auth/login/email/', data)

X-Forwarded-For spoofing / wrong IP in rate limiting

Cause: The app is behind a proxy but TENXYTE_TRUSTED_PROXIES is not configured.

Fix: 

TENXYTE_TRUSTED_PROXIES = ['10.0.0.1']  # your proxy/load balancer IP

Only IPs in this list will have their X-Forwarded-For header trusted.

Multi-Tenant / Organizations

404 ORG_NOT_FOUND

Cause: The X-Org-Slug header value does not match any existing organization.

Fix: Double-check the slug value. Slugs are lowercase and URL-safe: 

curl -H "X-Org-Slug: acme-corp" http://localhost:8000/api/v1/auth/organizations/members/

403 ORG_MEMBERSHIP_REQUIRED

Cause: The authenticated user is not a member of the organization specified in X-Org-Slug.

Fix: Add the user to the organization first via the admin or the invitation endpoint: 

POST /api/v1/auth/organizations/invite/
{
  "email": "user@example.com",
  "role": "member"
}

TOTP / 2FA

QR code generated but TOTP codes always rejected

Cause 1: Server clock drift exceeds TENXYTE_TOTP_VALID_WINDOW.

Fix: Increase the tolerance window (accepts ±N × 30-second periods): 

TENXYTE_TOTP_VALID_WINDOW = 2  # default is 1

Cause 2: TOTP secret is encrypted but FIELD_ENCRYPTION_KEY changed since setup.

Fix: Ensure FIELD_ENCRYPTION_KEY has not changed. If it has, follow the key rotation procedure.

Backup codes not accepted

Cause: Each backup code is single-use. Once consumed it cannot be reused.

Fix: Regenerate backup codes: 

POST /api/v1/auth/2fa/backup-codes/

Social Authentication

Google OAuth: invalid_grant or redirect loop

Cause: GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET are incorrect, or the redirect URI registered in Google Console does not match.

Fix: 1. Verify credentials in Google Cloud Console → APIs & Services → Credentials 2. Ensure the redirect URI matches exactly (including trailing slash): 

http://localhost:8000/api/v1/auth/social/google/callback/

WebAuthn / Passkeys

InvalidStateError during registration

Cause: The WebAuthn challenge has expired (default: 300 seconds) or was already consumed.

Fix: Re-initiate the registration flow: 

POST /api/v1/auth/webauthn/register/begin/

Database

OperationalError: no such table for Tenxyte models

Cause: Migrations were not run after installing Tenxyte.

Fix: 

python manage.py migrate

If the table still does not appear: 

python manage.py showmigrations tenxyte
python manage.py migrate tenxyte

Getting Further Help

  1. Check the Settings Reference — the setting you need may already exist
  2. Review the Security Guide for security-related issues
  3. Check the TESTING.md for test setup problems
  4. Search open issues or ask on the community forum