Home
Blog
Showcase
Community
Introduction
Overview
Introduction To TinaCMS
Getting Started
Using the Tina Editor
FAQ
Core Concepts
Content Modeling
Data Fetching
Visual Editing
Querying Content
Overview
Writing custom queries
Editing
Overview
Markdown & MDX
Block-based editing
Single Document Collections
Customizing Tina
Overview
Validation
Custom Field Components
Custom List Rendering
Format and Parse Input
Filename Customization
Before Submit function
Going To Production
Overview
Tina Cloud
Self-Hosted
Drafts
Overview
Draft Fields
Editorial Workflow
Guides
Overview
Framework Guides
Separate Content Repo
Querying Tina Content at Runtime
Internationalization
Migrating From Forestry
Overview
Setting up Tina
Common Errors & Fixes when Migrating to TinaCMS
Comparing Forestry & Tina Concepts
Missing Forestry Features
Further Reference
Overview
Config
Schema
The "tina" folder
The TinaCMS CLI
Media
Search
Content API
Tina's edit state
The "tinaField" helper
Self-Hosted Components

Here is a list of the the common things that someone may run into when migrating from Forestry to TinaCMS.

Migrating fields with non alphanumeric characters

In TinaCMS all fields can only contain alphanumeric characters or underscores. While in forestry you could have fields with non alphanumeric characters, such as my-field-name or my field name.

TinaCMS provides a nameOverride property, that allows you to specify how a field with special characters gets output.

E.g:

// collection fields
{
name: `my_field_name`,
nameOverride: `my-field-name`
}
The Forestry migration tool (npx @tinacms/cli init) should automatically apply nameOverride when importing your templates.

Migrating Blocks

_template vs template

The concept of using blocks as field types in forestry is supported in TinaCMS as providing templates in an object field. During the migration, the migration tool will convert your blocks into templates.

In TinaCMS, instead of the template key we use _template by default. The forestry migration tool will handle this automatically by setting the templateKey to "template" for Forestry sites, but it's something to be aware of.

Using dashes in block names

In TinaCMS, it is common for front matter templates to have - in the name. TinaCMS doesn't natively support dashes in a field name, however it does support a nameOverride property to handle this case.

For example if you had a front matter template that looked like this.

---
label: landing-page
fields:
- type: blocks
name: sections
label: Sections
template_types:
- call-to-action
- feature
- hero

And content that looked like this

sections:
- template: call-to-action
# ...
- template: feature
# ...

Then in Tina, your block field would look like:

// ...
{
type: "object",
list: true,
name: "sections",
label: "sections",
templateKey: 'template',
templates: [
{
name: 'call-to-action',
nameOverride: 'call_to_action',
fields: [
//...
]
},
// ...
]
}

Your output content would continue to look like:

- template: call-to-action
# ...
# this assumes your block has templateKey: 'template' set on your blocks field.
- template: feature
# ...

Common error message and how to fix them

Error: Block template "TemplateName" is not defined for field "FieldName"

In forestry you could have a block field that had a template that was not defined in the front matter template. In TinaCMS, this is not allowed. You will have to add the template from forestry to to the list of templates in the blocks field and define the fields for that template.

See a more in depth video explaining here

Error when getting content in the admin

[Error] GetCollection failed: Unable to fetch, errors: Error querying file <File> from collection pages. Please run "tinacms audit" or add the --verbose option for more info

This can happen for many reasons. Some common reasons are because the data you are trying to fetch is

  • not in the correct format
  • missing a required field
  • is missing the _template key. If you look at the error message in the terminal you should see the exact error that is causing the issue.

For example, if you are missing _template you will see an error like this

Error: Unable to determine template for item at hugo/content/about.md, no template name provided for collection with multiple templates
at TinaSchema.getCollectionAndTemplateByFullPath (/Users/logananderson-forestry-mac/dev/forestry.io/forestry.io/node_modules/@tinacms/schema-tools/dist/index.js:224:19)

This can be fixed by adding the _template key to the front matter of the file.

---
# ...
_template: my_template
---

..where "my_template" is the name of the template in the collection to which the file belongs.

Error YAMLException: duplicated mapping key

This happens when you have two keys in the frontmatter of your markdown files that are the same. In forestry, this was allowed but in TinaCMS it is not. You will have to remove one of the keys.

For example, if you have a file that looks like this

---
date: 2021-01-01
date: 2021-01-02
---

It will have to be changed to

---
date: 2021-01-02
---

Info: Match was transformed to newMatch

The match property works a bit differently in TinaCMS than it does in Forestry. In Forestry, the match property is a glob pattern that includes the file extension. In TinaCMS, the match property is a glob pattern that does not include the file extension.

In TinaCMS the match property is set for each collection and is nested.

{
label: 'Pages',
name: 'pages',
match: {
include: "{foo,ba}/**/*"
}
//..
}

Check out the match property docs for more info.

Since this migration tool is converting from Forestry to TinaCMS, it will automatically convert the match property to the TinaCMS format. It is a good idea to double check that it is matching correctly.

Last Edited: August 30, 2024

Product

Showcase
TinaCloud
Introduction
How Tina Works
Roadmap

Resources

Blog
Examples
Support
Media

Whats New
TinaCMS
TinaCloud
Use Cases
Agencies
Documentation
Teams
Jamstack CMS
Benefits
MDX
Markdown
Git
Editorial Workflow
Customization
SEO
Comparisons
TinaCMS vs Storyblok
TinaCMS vs Sanity
TinaCMS vs DecapCMS
TinaCMS vs Contentful
TinaCMS vs Builder.io
TinaCMS vs Strapi
Integrations
Astro
Hugo
NextJS
Jekyll