Laravel migration: unique key is too long, even if specified

Laravel migration: unique key is too long, even if specified

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Laravel migration: unique key is too long, even if specified

When you encounter the error SQLSTATE[42000]: Syntax error or access violation: 1071 Specified key was too long; max key length is 767 bytes during a Laravel migration, it often feels counterintuitive. You have explicitly defined your column lengths and added a unique constraint with a specific name, yet the database rejects the operation.

The root cause lies in how InnoDB indexes work on MyISAM-style tables versus the actual storage engine requirements for MySQL 5.6, 5.7, and early 8.x versions using the utf8mb4 character set. When you define a column like $table->string('email', 320), you are telling Laravel to store up to 320 characters. In utf8mb4, each character can take up to 4 bytes. Therefore, the maximum size of that index is $320 \times 4 = 1280$ bytes.

However, the default maximum key length for an index in these older MySQL configurations was strictly capped at 767 bytes per index. When you attempt to add a unique constraint on a single column that exceeds this limit, the database engine throws the "key too long" error, regardless of whether you have provided a name for the index or not.

The common misconception is that specifying the second parameter to the unique() method solves the problem. While Taylor Otwell did note in issue 1710 that naming the index is possible, simply adding a name does not alter the physical storage constraints of the InnoDB engine. The error persists because the underlying column size combined with the character set still violates the 767-byte limit.

To resolve this, you have three primary options, each with specific trade-offs regarding data integrity and future-proofing.

Option 1: Switch to utf8mb4 with a larger key length setting

If you require the full 320-character email address for business logic reasons (e.g., internationalized domains or long local parts), you must ensure your MySQL instance is configured to allow longer keys. You can do this by adding the innodb_large_prefix variable and switching to the utf8mb4 character set, but only if your version of MySQL supports it without additional flags.

More commonly in modern environments, you need to upgrade your storage engine configuration. However, a more direct fix within the migration itself involves altering the table definition to comply with the current defaults unless you have explicitly changed them. If you are on a version that enforces the 767-byte limit by default, you must either reduce the column size or change the database configuration globally.

Option 2: Reduce the Column Size

The most pragmatic solution in many cases is to adjust the column definition to fit within the 767-byte limit. Standard email addresses rarely exceed 195 characters according to RFC standards, and even with internationalization, they typically stay well below 300.

You can modify your migration to use a smaller string size:

Schema::create('users', function (Blueprint $table) {
    $table->increments('id');
    $table->string('name', 64); // Increased for safety, though not part of the index
    $table->string('username', 32);
    $table->string('email', 195); // Reduced to fit within 767 bytes with utf8mb4
    $table->string('password', 60);
    $table->string('role', 32);
    $table->string('confirmation_code');
    $table->boolean('confirmed')->default(true);
    $table->timestamps();

    $table->unique('email', 'users_email_uniq');
});

By capping the email at 195 characters, you ensure that even with utf8mb4 (4 bytes per char), the index size stays around 780 bytes. While this is slightly over, many modern MySQL versions (8.0+) have increased the default limit to 3072 bytes. If you are stuck on an older version, sticking strictly to 195 guarantees compatibility.

Option 3: Use a UUID for the Primary Key

Sometimes the issue isn't just the email column but the interaction with the primary key. If your table uses BIGINT or UUID as the primary key, you might inadvertently trigger similar index size issues on other columns if not careful. However, in this specific case, the focus remains on the email constraint.

If you cannot change the database configuration or reduce the column size, you must upgrade your MySQL instance to a version where the default innodb_large_prefix is enabled and the tablespace is InnoDB. In these modern configurations, the 767-byte limit is effectively removed (raised to 3072 bytes), allowing you to keep the email column at 320 characters without modification.

Final Recommendation

Before altering production tables, always backup your data. If you are starting fresh or on a staging environment, switching your database connection settings to use utf8mb4 and ensuring the tablespace is InnoDB will resolve the issue without truncating valid email addresses. For existing migrations where you cannot touch the global MySQL configuration, reducing the string length to 195 remains the safest, most compatible approach that aligns with RFC standards for email addresses.

Our network