Custom error message using CodeIgniter Form Validation

Custom error message using CodeIgniter Form Validation

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

Stefan Bogdanescu

Founder & Senior Architect

Custom error message using CodeIgniter Form Validation

When building forms in CodeIgniter, the default validation messages often feel too generic for production applications. You might encounter the standard "The username is already taken" message when a user tries to register, but that same string appears regardless of whether the field is a username, an email, or any other unique identifier. While editing form_validation_lang.php seems like a quick fix, it lacks granularity; you cannot distinguish between a duplicate username error and a duplicate email error using just the generic is_unique key in the language file.

To achieve specific messaging for different fields, you need to leverage the dynamic nature of CodeIgniter's validation engine. The core mechanism lies in how the framework maps rules to messages. When you call $this->form_validation->set_message(), the first argument is a rule name, and the second is the custom text. However, simply passing the full rule string like 'is_unique[users.username]' to set_message() often fails because the validation engine expects the raw rule segment without the field name suffix for the lookup key.

The correct approach involves stripping the field name from the rule before registering the custom message. You should target the specific error code that the validator generates. For database uniqueness checks, CodeIgniter generates an error with the code is_unique. If you pass 'is_unique[users.username]' to set_message, the system looks for a key that matches exactly, which won't exist in your language array or internal logic.

Instead, isolate the error code:

$this->form_validation->set_message('is_unique', 'The username is already taken');

This tells the engine, "Whenever you encounter an is_unique failure, display this text." However, there is a nuance here. The default message for is_unique is pluralized and often includes placeholders like {field}. If you want to be strictly specific about which field failed without relying on placeholders, you might need to handle the logic differently depending on your CI version. In many modern setups, the validation library dynamically constructs the error string using the field name if you define a custom message for the generic is_unique rule.

Consider this scenario where you only want to validate uniqueness when the username has actually changed:

$username = $this->input->post('username');
$existing_username = $user->username; // Assume this is loaded from session or DB

if ($username !== $existing_username) {
    $rules['username'] = [
        'field' => 'username',
        'label' => 'Username',
        'rules' => 'trim|required|min_length[4]|max_length[20]|is_unique[users.username]'
    ];

    // Register the custom message specifically for the is_unique rule segment
    $this->form_validation->set_message('is_unique', 'The username you entered is already taken.');
    
    $this->form_validation->run();
}

By removing the [users.username] part from the key passed to set_message, you align with how the validation library indexes its error messages. The library then automatically appends the relevant field name (e.g., "username") to your custom message if it contains a placeholder, or simply uses your string as-is.

If you require distinct messages for different fields—such as distinguishing between a taken username and a registered email—you may need to register multiple custom messages for the same error code. This is possible in CodeIgniter by providing an associative array of rules and messages to set_message, although this syntax is less common in older versions. In most practical cases, defining one clear message for is_unique that reads naturally when applied to any unique field is the cleanest solution.

Another option, particularly if you are using CodeIgniter 4, is to define a custom validation callback function. This gives you full control over the error message string within the context of that specific rule. You can return a custom string directly from the callback, bypassing the need to configure global messages. For example:

$this->form_validation->set_rules('username', 'Username', 'trim|required|callback_check_username_unique');

public function check_username_unique($username) {
    $query = $this->db->get_where('users', ['username' => $username]);
    if ($query->num_rows() > 0) {
        return false; // Validation fails
    }
    return true;
}

While this requires writing a callback, it ensures the error context is explicitly defined within your business logic rather than relying on global configuration. This method also allows you to inject dynamic data into the error message if needed, such as suggesting alternative names.

Ultimately, the key is understanding that set_message keys must match the rule segment generated by the validator, not the full expression including the field name. By targeting is_unique directly, you ensure your custom messages apply consistently across your application without cluttering language files with ambiguous entries.

Our network