🔧 [Refactor] For Directus Updates >11.9.3 adapt Authentication Flows and Seeding Mechanism

[mahula]

🔧 Refactor

Updating Directus further to versions >11.9.3 will require to adapt our authentication flows and seeding mechanism due to breaking changes.

Higher versions of Directus require directus-sync 3.4.1 and @directus/sdk 20.0.0 to work properly, which in sum requires adaptation of

Authentication Flows

// current (SDK 17.0.2) 
directusClient.login(email, password, { mode: 'json' })

// SDK 20.x
directusClient.login({ email, password }, { mode: 'json' })

and

Our Seeding Mechanism

Backend seeding will fail with ConflictError: Local id already exists when u

Upgrading to Directus 11.10.0+ with directus-sync 3.4.1+ fails our backend seeding with ConflictError: Local id already exists.

That is caused by System Collection Exclusion: Directus 11.10.0 introduced breaking change #25271 that excludes system tables (like directus_settings) from snapshots, but our configuration still contains system collection data.

The file backend/directus-config/development/collections/settings.json contains Directus project settings but has no corresponding schema definition in snapshot/, creating a data/schema mismatch.

🔧 Required Actions Before Upgrading

Step 1: Clean Up System Collection Files

Remove system collection data files that are no longer supported:

# Remove settings data (will be managed by Directus directly)
rm backend/directus-config/development/collections/settings.json

# Check for other system collections and remove if present
rm backend/directus-config/development/collections/users.json     # if exists
rm backend/directus-config/development/collections/roles.json     # if exists  
rm backend/directus-config/development/collections/policies.json  # if exists

Step 2: Update Sync Tool First

Always upgrade directus-sync before Directus backend:

# In backend/seed.sh - update sync version
npx directus-sync@3.4.1 push \
  --dump-path $PROJECT_FOLDER \
  # ... rest of parameters

Step 3: Test Seeding

# Test with dry-run first
cd backend
./seed.sh --dry-run  # if supported, or test in development

# Verify no ConflictErrors occur

Step 4: Update Directus Backend

# In backend/Dockerfile
FROM directus/directus:11.12.0  # or latest

💡 Alternative: Manual Settings Migration

If you need to preserve current settings:

1. Export current settings from Directus admin panel
2. Remove settings.json from sync configuration
3. Manually reconfigure settings in new Directus instance
4. Document settings in project documentation for future reference