MySQL Docker 'unknown variable default-authentication-plugin' Error

Problem Statement

When running a MySQL 8.4 container with Docker Compose, you encounter the error:
unknown variable 'default-authentication-plugin=mysql_native_password'

This occurs because MySQL 8.4 changed its authentication plugin configuration syntax. The old parameter default-authentication-plugin used in either:

1. The container's command: argument in docker-compose.yml
2. The my.cnf configuration file

Is no longer valid in MySQL 8.4. The same setup might have worked with MySQL 5.7, but fails when migrating to newer versions due to deprecated authentication system parameters.

Solution

Understanding the Changes

MySQL 8.4 replaces the legacy default-authentication-plugin parameter with explicit plugin management. The solution requires:

1. Using the correct syntax for enabling mysql_native_password
2. Removing unsupported parameters from configuration files

Step-by-Step Fix

1. Modify your docker-compose.yml:
   Replace the incorrect command parameter with valid syntax:

db:
    image: mysql:8.4
    command: ["mysqld", "--mysql-native-password=ON"]  # Updated line
    restart: unless-stopped
    ports:
        - 3306:3306
    environment:
        MYSQL_RANDOM_ROOT_PASSWORD: 'yes'  # Ensure strings are quoted
        # Keep other environment variables unchanged
    volumes:
        - mysql_dev:/var/lib/mysql
        - ./docker/laravel/config/mysql/my.cnf:/etc/mysql/conf.d/my.cnf

2. Update your my.cnf file:
   Comment out or remove the invalid parameter:

[mysqld]
mysql_native_password=ON
# default-authentication-plugin=mysql_native_password  <-- Disable this
general_log = 0
general_log_file = /var/lib/mysql/general.log
default_time_zone='+00:00'

3. Rebuild your container:
   After making these changes, run:

docker compose down --volumes  # Removes old volumes
docker compose up -d --build    # Recreates container with new config

Why This Works

• The --mysql-native-password=ON flag explicitly enables the legacy authentication plugin at startup
• MySQL 8.x introduced this new syntax to replace the deprecated default-authentication-plugin
• The environment variable MYSQL_AUTHENTICATION_PLUGIN: mysql_native_password is still valid and works alongside this configuration

Best Practices

1. Avoid mixing configuration methods: Choose either:

   • Environment variables (recommended for Docker)
   • Configuration files (my.cnf) Not both simultaneously to prevent conflicts

2. Authentication plugin considerations:
   !!! warning "Security Note"
   The mysql_native_password plugin is less secure than MySQL 8.0+'s default caching_sha2_password. Only use it for legacy application compatibility.

# Recommended for new projects (remove command line):
environment:
    MYSQL_AUTHENTICATION_PLUGIN: caching_sha2_password

Verifying the Fix

1. Check MySQL server variables:

docker compose exec db mysql -u root -p -e \
"SHOW VARIABLES LIKE 'default_authentication_plugin';"

2. Test client connections with native password authentication:

mysql -u your_user -p --protocol=tcp -h localhost

Key Takeaways

• MySQL ≥8.0 deprecated default-authentication-plugin configuration
• Always reference the MySQL Server System Variables documentation for your specific version
• Docker environment variables often provide cleaner configuration than command-line arguments
• Full error context is available with: docker compose logs db

This solution maintains compatibility while allowing you to use current MySQL versions, bridging the gap between legacy authentication requirements and modern MySQL deployments.