How to fix “Failed to update columns dictionary object” error in Craft CMS

Several months ago I was working on a Craft CMS website that used a content builder, which meant heavy use of the Matrix field type which allows for what I call “subfields” (i.e. field within a Matrix block). In any case, everything was working fine until I tried to delete a subfield. I don’t recall the exact error, but it was something similar to Failed to update columns dictionary object. Gotta love cryptic errors like this. 😆

That was an error I had never seen before in building Craft websites. So I put on my researcher hat on and found out what the issue was/is.

The culprit

In MySQL 8, database column names have a limit of 53 characters. Odd number, but reasonable I would think.

In Craft, each Matrix field is given its own table in the database that is prefixed with matrixcontent. The name of the Matrix field is added to this, separated by an underscore. So a Matrix field called Content Blocks with a handle of contentBlocks will have its own table in the database and would be named matrixcontent_contentblocks. Each subfield is in a column within the table. So if we have a CTA block (handle: cta) in a Matrix field block with a plain text heading field (handle: heading), the column name might look like this: field_cta_heading_abcdefg.

Note the _abcdefgh at the end. I’m not going to pretend I know what that is other than an underscore and string of 8 alpha characters, but Craft adds something this to the column name. It’s never the same for any two fields, so I assume it’s to avoid duplication, but I have no idea, nor do I pretend to know or understand database schemas. My point here is that regardless of what your Matrix block and subfield are called, the database is adding 6 characters up front (field_) and 9 characters at the end (_abcdefgh), leaving you with 38 characters if we do the math go by the 53 character limit in MySQL 8. Still a reasonable number I think.

The thing is, when you’re adding new fields or editing fields within a Matrix block, the number of characters doesn’t matter. MySQL happily accepts whatever it’s given for the column name. It’s when you try to delete the Matrix block field in the Craft back-end that you run into the aforementioned error.

Solution

The solution turned out to be pretty simple: rename the field in the Matrix block to something shorter, save it, then delete it. That’s it. No more error.

Hat tip to Tom Schlick who had the foresight to write about the issue with regard to Laravel back in 2022.