SQLSTATE[HY093]: Invalid parameter number: parameter was not defined

SQLSTATE[HY093]: Invalid parameter number: parameter was not defined

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

Stefan Bogdanescu

Founder & Senior Architect

SQLSTATE[HY093]: Invalid parameter number: parameter was not defined

When working with Yii's Active Record, you often rely on its built-in query builder to handle database interactions seamlessly. However, the moment you switch to Yii's Data Access Object (DAO) pattern to access a secondary database for a specific transaction, the abstraction layer can sometimes trip you up. A common stumbling block is encountering the cryptic error SQLSTATE[HY093]: Invalid parameter number: parameter was not defined.

This error occurs when there is a mismatch between the named placeholders defined in your SQL statement and the parameters actually passed to the command object via bindValue(). In the scenario provided, the application constructs an INSERT statement using placeholders like :alias, :password, and :surname. Yet, when executing the command, the code attempts to bind a value for :username—a parameter that was never declared in the SQL string.

Consider this specific implementation detail from the source material:

$sql = "INSERT INTO users (username, password, ssn, surname
        , firstname, email, city, country) 
        VALUES(:alias, :password, :ssn, :surname
        , :firstname, :email, :city, :country)";

$command = $connection->createCommand($sql);
$command->bindValue(":username", $model->alias); // Mismatch!

The SQL statement explicitly defines :alias as the first placeholder corresponding to the username column. However, the binding operation targets :username. Because PDO validates that every bound parameter exists in the prepared statement, it throws SQLSTATE[HY093] immediately upon execution.

To resolve this, you must ensure strict consistency between your SQL placeholders and your binding calls. If you intend to use :alias in the query, bind :alias. If you prefer using :username in the code, you must update the SQL string accordingly. The fix involves aligning the parameter names so that every bindValue() call corresponds to an existing placeholder in the VALUES clause.

$sql = "INSERT INTO users (username, password, ssn, surname
        , firstname, email, city, country) 
        VALUES(:username, :password, :ssn, :surname
        , :firstname, :email, :city, :country)";

$command = $connection->createCommand($sql);
$command->bindValue(":username", $model->alias);      // Now matches SQL
$command->bindValue(":password", substr($model->ssn, -4, 4));
$command->bindValue(":ssn", $model->ssn);
// ... and so on for the remaining fields

It is also worth noting a potential logical pitfall in the original snippet. The code binds :firstname to $model->firstName but then binds :city to $model->placeOfBirth. While this might be intentional based on legacy data requirements, it highlights the importance of double-checking that your variable mappings reflect your actual business logic. Using a single property like placeOfBirth for both city and country columns can lead to data integrity issues if not carefully considered during schema design or migration.

If you are maintaining a large codebase or migrating from an older version of Yii, be aware that the DAO pattern requires manual management of these bindings. In modern Laravel applications, this complexity is often abstracted away by Eloquent's query builder, which handles parameter binding automatically. If you find yourself struggling with raw SQL and parameter binding in a new project, frameworks like Laravel offer a robust alternative where such mismatches are less likely to occur unintentionally.

Ultimately, the HY093 error is a safeguard against silent data corruption. It forces you to confront the exact mapping between your query syntax and your data source, ensuring that every variable inserted into the database has a clearly defined and matched counterpart in your code.

Our network