Key Points About Bulk Delete

• Delete Users by Query is driven by the search index (specifically Elasticsearch). The queryString parameter has limited support when using the database as the search engine (only simple single-term searches on basic fields like firstName, lastName, fullName, email, and username).
• CloudFront has a 30-second timeout for origin responses, which explains the 504 errors you're seeing
• The delete operation likely continues on the FusionAuth side even after CloudFront terminates the connection, making retries risky

Recommended Approach: Tenant Delete/Recreate

For test environments with large user populations, follow this workflow:

1. Cannot delete the Default tenant — the default tenant contains the FusionAuth application and cannot be deleted. Create separate tenants for testing purposes.
2. Delete the test tenant when ready to reset using the admin UI or the Delete Tenant API. This will permanently delete all users, applications, and groups belonging to that tenant.
3. Use docker compose down -v to fully clean the environment
4. Use docker compose up -d to restart
5. Use Kickstart to automatically recreate tenants, applications, and API keys

Kickstart will only run on an empty instance, so the down -v step is necessary. Configure a Kickstart file with your test environment configuration (tenants, applications, API keys) for reproducible deployments.

Note that tenant deletion is an asynchronous operation (as of FusionAuth 1.22), meaning it runs in the background. For very large tenants (2M users), this will still take time but is considerably faster than bulk deleting millions of users through the API.

Note on Import Timeouts

If you're also seeing CloudFront timeouts during large batch imports (e.g., 100k users), the same 30-second CloudFront limit applies. Consider reducing batch sizes when users have multiple registrations, as each registration inserts additional rows into related tables (registrations, application role mappings, etc.), significantly increasing processing time. For best import performance, minimize network hops and consider setting validateDbConstraints to false.

Related Documentation

• Delete Tenant API - API for permanently deleting a tenant and all its users
• Bulk Delete Users API - API for deleting users by query, with limitations noted for search engine configuration
• Kickstart - Declarative tool for quickly replicating environments
• Clean Up Test Environments - Migration guide with recommendations for test tenant cleanup
• How to Delete Users After Testing a Migration - Documentation on fastest methods for removing test users
• Asynchronous Tenant Deletion - Background on how tenant deletion works asynchronously
• Import Users API - Bulk import API documentation
• Performance Tips for Migrations - Best practices for importing large numbers of users