Fixing the missing Model and AppModel replacement errors

This article is over a year old and may contain outdated information.

If you are a CakePHP developer, I am almost certain you have run into this problem on multiple occasions. What problem are you referring to you ask? Well, the problem that you have when your model is not being found and Cake automatically substitutes it with AppModel. Cake does this on purpose so that your relations and HABTM's do not need the junction Model to operate correctly. This works in most cases, but sometimes you get some weird errors or missing method problems. But before I continue with this, lets setup a quick scenario so I can better explain this problem. I will be using an example of relating users to teams.

User Model - users Table
Team Model - teams Table
TeamsUser Model - teams_users Table (Join)

User -> hasAndBelongsToMany -> Team
Team -> hasAndBelongsToMany -> User
TeamsUser -> belongsTo -> User, Team

In our code we are stating that a user can be on multiple teams, and a team can have multiple users. Are relation seems pretty simple, but lets not rely on Cake to magically figure everything out. In some cases we would receive the following errors:

  • Model "User" is not associated with model "Team"
  • Warning (512): SQL Error: 1064: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'myCustomMethod' at line 1 [CORE\cake\libs
    \model\datasources\dbo_source.php, line 514] Query: myCustomMethod

Now what do those errors mean? Well the first one states that our Models can not be related. So the first thing we need to do is check that our Models naming conventions are correct: model names are singular and camelcased, where as the filenames are singular, underscored and lowercased (without having _model in the filename). The second error means we are trying to call a method on a Model that does not have that method in its class. In other words, it basically means our Model is not being loaded and the AppModel is being loaded in its place. This happens when Cakes naming magic fails to load the correct Model or we have improperly followed conventions.

Most of these problems can be fixed by following the proper naming conventions. I'd also like to note that most of these errors appear during HABTM relations, and can easily be fixed with the following:

  • With any relation, its best to define the "className" parameter. By doing this, we are telling Cake the exact name of our Model, instead of having Cake rely on the relation name (which can easily be changed to custom text).
  • When defining conditions or containments, be sure to include the model name followed by the column name: Model.field
  • Important! When working with complex HABTM relations, define the "className, joinTable and with" parameters. If you have complex relations with crazy table names, its highly required you define the joinTable and with parameters.

During one of my projects, I had a Model that had a HABTM relationship, in which that HABTM had its own HABTM relationship, so it got quite complex. I ran into problems over and over again where Models would not be related and the AppModel was used instead. I later found out that the problem was the with parameter. Since I didn't define it manually, Cake could not figure out the correct HABTM Model to use, hence the whole application broke. Its pretty funny that my whole app didn't work for weeks, all based on this small declaration.

So, since we know how to fix this problem, lets define our relations:

class User extends AppModel {

	public $hasAndBelongsToMany = array('Team' => array(
		'className' => 'Team',
		'joinTable' => 'teams_users',
		'with' => 'TeamsUser',
		'foreignKey' => 'user_id',
		'associationForeignKey' => 'team_id'


So in conclusion, follow the naming conventions and define the required parameters when creating relations, and I promise you, you won't have any problems.


  • @Brendon Kozlowski - No you are right, the relationship is not need for HABTM to work, hell the model itself isn't even required.

    Although, more times then not I (and possible you) will need to use the HABTM by itself (e.g., custom methods, pagination or containing data), so its just good practice to create the model and place its relations.
  • TeamsUser -> belongsTo -> User, Team

    Are you actually defining this relationship anywhere? I don't believe that's necessary unless you are actively manipulating this table on your own, and not letting Cake handle it automatically. Following Cake conventions, I don't think it has to be defined if it's set in the "with" property of related models.

    That being said, I (thankfully) haven't messed around with too many HABTM relationships in my projects, and those I have were rather simplistic.
  • Ah yes your right, just a small typo. Most likely got confused when having to keep singularizing all the model names. Fixed.
  • should the join table not be teams_users

    TeamsUser Model - teams_users Table (Join)