Troubleshooting TinaCloud

TinaCloud's GraphQL API returns this error when it cannot find a file in your GitHub repository. This may occur under the following circumstances:

• The tina folder (and __generated__ subfolder) is not in your GitHub repository remote
  • If the folder is in your local repository, but not in your remote, make sure there isn't a .gitignore file excluding it
• Tina is configured with a branch that doesn't exist or a branch that doesn't contain the tina folder
  • The referenced branch should be created and should contain the tina folder
• The apiURL prop is misconfigured on the TinaCMS component
  • Check the apiURL and make sure it looks like https://content.tinajs.io/content/{tina_client_id}/github/{branch} where {tina_client_id} matches the Client ID on the Project in TinaCloud and {branch} is a valid branch

If you are getting this error in your build logs, it means that the tina/tina-lock.json in your deployed site doesn't match the version that is in TinaCloud. To resolve it:

1. Ensure that your schema (generated from tina/config.ts) does not include any varying information, such as timestamps or random text
2. Ensure that you have the latest versions of @tinacms/cli and tinacms in your project
3. Run the dev command locally
4. Commit any changes to the tina/tina-lock.json and push those to the git repository linked in TinaCloud

If you are getting this error when access the TinaCMS interface, it can be caused by a mismatch between the version of tinacms and @tinacms/cli on the project. Update both dependencies to the latest versions and run the dev command locally. Commit any changes to the tina/tina-lock.json and push those to the git repository linked in TinaCloud.

If you receive an error like The specified branch, 'my-branch-name', has not been indexed by TinaCloud, or see no branches indexed at all, try the following:

1. Ensure tina/tina-lock.json exists and is committed to your repository. This is the most common cause of branches not being indexed. The tina-lock.json file is generated when you run tinacms dev locally — it is not generated by tinacms build alone. Run tinacms dev (or your wrapped dev command like yarn dev), then commit and push the generated tina/tina-lock.json file. See Adding Tina to an Existing Site for more details.
2. Verify that a configuration file exists at tina/config.ts on the default branch
3. Verify that the correct branch has been specified in the config properties passed to defineConfig in tina/config.ts. Note, that this value may be set as an environment variable in your CI build process
4. Verify that the branch exists in the GitHub repository
5. Pull down the branch into your TinaCloud project. Video: Why TinaCloud Works So Well with GitHub | TinaCMS Data Layer | Eli Kent (3 min)
6. You can also force a branch to be reindexed by TinaCloud by making a whitespace change to the tina/tina-lock.json file in that branch, committing it, and pushing it to GitHub. This will initiate indexing for the branch, and (after a few minutes) the error should be resolved
7. Ensure that the Tina project is located in the root directory

When using TinaCloud without Editorial Workflow, you need to ensure that the TinaCloud App is able to commit to the selected branch of the repository.

If it cannot, you will see an error of the following form:

Video: FAQ - Bypassing GitHub branch protection with TinaCMS (3min)

Generally this happens when there is branch protection on your main branch and TinaCloud is unable to bypass it. Until July 2024, the TinaCloud GitHub app had admin rights to repositories which allowed it to bypass these rules for most repositories.

To fix this issue, either:

• Upgrade from legacy branch protection to branch rulesets - https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository
  Ensure that the TinaCloud app is allowed to bypass the rule requiring branch protection
• Enable Editorial Workflow to create PRs on the branch

The current branch that Tina is using is invalid or undefined. Double check that the correct branch is selected and it does in fact exist.

You can view the branches that have been indexed by TinaCloud by visiting https://app.tina.io/projects/<your-project-id>/configuration.

Figure: Branches indexed by TinaCloud

Everything in the tina directory (except the __generated__ folder) needs to be pushed up to the git repository. Be sure to add it to your git repository (and make sure you don't have it listed in a .gitignore). Also make sure that the branch you're trying to use has the tina directory and is up to date.

The ContentAPI URL isn't formatted correctly. See our TinaCloud URL formatting guide for information on how the URL should be formatted.

When logging into TinaCloud, the URL of the website you're attempting to login from is sent via the ?origin= URL parameter. This error can occur when the URL specified in the ?origin= URL parameter of the auth window does not match one defined within your TinaCloud Site URLs.

To resolve this, ensure that one of the URLs specified in your TinaCloud Site URLs settings exactly matches that shown in the ?origin= URL parameter.

Figure: URL parameter

Figure: TinaCloud Site URLs settings

Sometimes the editorial gets stuck on the updating branch step. When you see this, make sure to check project is set to the correct repository.

Figure: TinaCloud repository settings

The TinaCloud login flow redirects through several external domains (AWS Cognito, API Gateway, GitHub) that may be blocked by your VPN or firewall. If any domain in the redirect chain is blocked, the login will time out before completing.

To resolve this, ensure your network allows outbound traffic to all domains listed on the Network Requirements page. Whitelisting *.tina.io alone is not sufficient — the authentication flow also requires access to AWS and GitHub domains.

To diagnose which domain is blocked, open your browser's DevTools (Network tab) and attempt to log in. Look for any requests that stall or fail.