tinacms: Renaming/Deleting file (that has references) leads to errors

Describe the issue that you’re seeing. Any Loom videos or screenshots usually help a lot!

If I change the file name of an author I get the following error: Screenshot 2023-11-27 195254

I can no longer access the Authors panel. Would be nice if an user renames an author file that everything get associated to that file name also get’s rename to the new file name to prevent any errors.

Reproduction

https://github.com/Remzi1993/tina-test

Steps to reproduce

Create a project in CLI with npx create-tina-app@latest Use Tailwind CSS as starter and go to localhost:3000/admin and click on Authors and change an author’s file name.

I used NPM

System Info

System:
    OS: Windows 11 10.0.22631
    CPU: (16) x64 AMD Ryzen 7 5825U with Radeon Graphics
    Memory: 694.11 MB / 15.31 GB
  Binaries:
    Node: 21.2.0 - C:\Program Files\nodejs\node.EXE
    Yarn: 1.22.19 - ~\Projects\test-tina-project\node_modules\.bin\yarn.CMD
    npm: 10.2.3 - C:\Program Files\nodejs\npm.CMD
  Browsers:
    Edge: Chromium (119.0.2151.72)
    Internet Explorer: 11.0.22621.1
  npmPackages:
    @tinacms/cli: ^1.5.34 => 1.5.34
    tinacms: ^1.5.24 => 1.5.24

Validations

About this issue

  • Original URL
  • State: closed
  • Created 3 years ago
  • Reactions: 2
  • Comments: 20 (6 by maintainers)

Most upvoted comments

Ha, I can confirm that as mentioned by @Remzi1993 there is no appropriate warning in the deletion message.

The rename functionality does seem to have a message but I would argue that this message only makes sense to developers. We know what references are and what the effect of unresolved references is. To content editors, this message isn’t very clear.

I can imagine full referential integrity being a complex issue @logan-anderson, there are probably lots of edge cases. I do think that most of the default issues can be solved quite easily. Say you’re working on file ./data/team-member/john-doe.json and it gets removed/renamed. It is easy to check the other JSON files for any reference to this file and update/remove it.

Indeed! You have described exactly what I mean. For us developers it’s not a problem, but I’m looking for a solution for the average user and person who wants to edit their website without understanding code or anything technical. I would like to replace WordPress (WP), because of PHP and other outdated tech and bloated code. Currently, WP adds 2 seconds to loading time and is a drag on everything. I use Vite and Vue, but you can’t expect non-technical users to code their own website. There are a lot of solutions out there, but they are all bloated and either use PHP or are too complex or too much for simple websites, like a bakery on the corner or a small bike shop, they don’t care and want to easily update their websites.

This is literally the only showstopper to make this CMS go big and be a WP replacement.

@Remzi1993 we currently do not have support for referential integrity in TinaCMS and have a warning when deleting or changing the name of files.

We are aware of this issue (it is a complex issue) and want to add support for referential integrity but we have no current plans for this to be added in the next 1-4 months.

✅ Done - This has been completed already in another PBI. Somehow we lost track of this one… https://github.com/tinacms/tinacms/issues/5209

Feature was released in version 2.5.0 of tinacms!

Adding to my previous comment, I might have found a way to hack Tina to skip the error admins see.

The hack consists in overriding cms.api.tina.request in the cmsCallback with a custom handling of:

  • Errors of type “Unable to find record…”
  • Valid responses but with data null, which happens after bypassing the first error and fetching a non-existing doc.

I leve here the snippet of code with comments, in case it helps anyone.

// have to load these dependencies, used inside request()
import { print } from 'graphql';
import gql from 'graphql-tag';

// ...

export default defineConfig({
  client: {
    errorPolicy: 'include', // to not make queries in preview mode (not in the editor) fail when something's wrong, like a missing author from a blog post.
  },

  // ... other properties

  cmsCallback: cms => {
    if (process.env.NODE_ENV === 'development') {
      window.cms = cms; // for debugging locally
    }

    /**
     * 💬 This is a modified copy of node_modules/tinacms/dist/index.mjs, Client.request (line ~27100)
     *
     * Error handling is modified to not fail when fetch() returns a missing reference error
     * because we don't want to block admins from editing when that happens.
     */
    cms.api.tina.request = async function (
      query: any,
      { variables }: { variables: Record<string, any> },
    ) {
      if (process.env.NODE_ENV === 'development') {
        console.log('[cms.api.tina.request] Start', variables);
      }

      const token = await this.authProvider.getToken();
      const headers2: Record<string, string> = {
        'Content-Type': 'application/json',
      };
      if (token == null ? void 0 : token.id_token) {
        headers2['Authorization'] =
          'Bearer ' + (token == null ? void 0 : token.id_token);
      }

      const res = await fetch(this.contentApiUrl, {
        method: 'POST',
        headers: headers2,
        body: JSON.stringify({
          query: typeof query === 'function' ? print(query(gql)) : query,
          variables,
        }),
      }).catch(err => {
        // 💬 printing in console when fetch() fails for debugging
        console.warn('[cms.api.tina.request] fetch error', err);
        throw err;
      });

      if (res.status !== 200) {
        let errorMessage = `Unable to complete request, ${res.statusText}`;
        const resBody = await res.json();
        if (resBody.message) {
          errorMessage = `${errorMessage}, Response: ${resBody.message}`;
        }
        if (!this.isCustomContentApi) {
          errorMessage = `${errorMessage}, Please check that the following information is correct:
	clientId: ${this.options.clientId}
	branch: ${this.branch}.`;
          if (this.branch !== 'main') {
            errorMessage = `${errorMessage}
	Note: This error can occur if the branch does not exist on GitHub or on Tina Cloud`;
          }
        }
        // 💬 printing in console non-ok responses for debugging
        console.warn('[cms.api.tina.request] Bad response', res);
        throw new Error(errorMessage);
      }

      const json = await res.json();

      // 💬 Edits here from original code of request().
      // excluding errors that have message "Unable to find record"
      // because they mean a missing reference, and we don't want to block users for that.

      type ResponseError = {
        message: string;
        path: string;
        locations: {
          line: number;
          column: number;
        }[];
      };

      const isErrorBlocking = (error: ResponseError) =>
        !error.message.includes('Unable to find record');

      const blockingErrors = ((json.errors ?? []) as ResponseError[]).filter(
        isErrorBlocking,
      );

      // 💬 Throwing only if there's another type of error
      if (blockingErrors.length > 0) {
        console.warn('[cms.api.tina.request] blockingErrors', blockingErrors);
        throw new Error(
          `Unable to fetch, errors:\n${blockingErrors
            .map(error => error.message)
            .join('\n')}`,
        );
      }

      // 💬 Since we're bypassing the error of "Unable to find record", Tina will then try to load the missing reference document
      // and the result will be `null`. To prevent downstream errors with data.node not being defined, we set it.
      // The page gets stuck in a loop trying to load the document. This gets fixed by changing the reference
      // Fortunately the sidebar can be interacted with!
      if (json.data === null && variables?.id) {
        if (variables.id) {
          alertOnce(
            `The document "${variables.id}" doesn't exist. Please update it in the sidebar.`,
          );
          // make the request wait, to make the continuous retry until the reference is fixed less impactful on the server load
          await new Promise(resolve => setTimeout(resolve, 3000));
        }
        return {
          node: { _internalSys: { path: '' } },
        };
      }
      return json.data;
    };
  },
});

// 💬 Small utility to only alert one time
const alertOnce = (() => {
  let alreadyAlerted = false;
  return (message: string) => {
    if (!alreadyAlerted) {
      alreadyAlerted = true;
      alert(message);
    }
  };
})();

With that, when there’s a broken reference, the admin user sees an alert, and then they can change the author value in the dropdown. For example:

Captura de pantalla 2024-06-07 a las 18 56 12 Captura de pantalla 2024-06-07 a las 18 56 22 Captura de pantalla 2024-06-07 a las 19 09 02

If I find later that this hack creates other problems, I’ll update this comment.

More than referencial integrity, I think the first step is not breaking the site for the user or the admin when there’s a broken reference.

For users, I found a solution. Setting the errorPolicy in the Tina config, at least now the preview of the site won’t break when an author reference is missing:

// in config.ts
export default defineConfig({
  client: {
    errorPolicy: 'include', // to not make queries fail when something's wrong, like a missing author from a blog post.
  },
  ...
});

For admins, I haven’t found a solution yet, because when opening a blog post with a broken author reference, an error like this pops up and the sidebar doesn’t load the edit form, so the admin is stuck with whatever content is in that blog and can’t fix the problem.

Captura de pantalla 2024-06-07 a las 17 42 12

If at least we could configure the GraphQL client in the editor with “errorPolicy” “include”, and fallback to an undefined value when a reference is broken, then at least nobody would be blocked and references could be fixed manually.

Ha, I can confirm that as mentioned by @Remzi1993 there is no appropriate warning in the deletion message.

The rename functionality does seem to have a message but I would argue that this message only makes sense to developers. We know what references are and what the effect of unresolved references is. To content editors, this message isn’t very clear.

I can imagine full referential integrity being a complex issue @logan-anderson, there are probably lots of edge cases. I do think that most of the default issues can be solved quite easily. Say you’re working on file ./data/team-member/john-doe.json and it gets removed/renamed. It is easy to check the other JSON files for any reference to this file and update/remove it.

I wonder if there’s a half-step here where we just warn the user upon certain actions (rename / delete) that this will break any active relationships.

  • Ideally we could conditionally show this only when documents have a reference to it, but an even easier step would be to always show it.

There is a warning when a user tries to change an author’s name, but there is no warning when you change the file name or the reverse. I forgot.

Thanks for sharing your thoughts. I think we share your that dream scenario.

Only one point of clarification, it doesn’t appear that Keystatic supports referential integrity. See the heads up note here https://keystatic.com/docs/fields/relationship.

@logan-anderson Thank you for the timeframe. I will check back a year later to be sure. In the meantime, the hobby projects and small websites from old friends will be running WordPress until that time comes.

I’ll point at that the number of users reporting issues with referential integrity is very low. If there were more users asking for it, I’m sure we would already have made it a higher priority, but that has not been the case so far. Fortunately, since Tina is Git-backed, it is pretty easy to recover from a mistake. There are lots of valid reasons to not migrate from WP to Tina, but unless your use-case is atypical, this is probably not one of them.

I would be more afraid that a user who has no technical knowledge would try to do things and then see errors leaving it to me to fix while a CMS should have given developers more time to spend on other things. I speculate that the user base of TinaCMS has technical knowledge otherwise they wouldn’t be able to use git and that would explain users reporting issues with referential integrity is very low. And as you said yourself revert an error is reverting a git commit. The problem is that the people outside the technical community and everyday users of society wouldn’t have knowledge of git. My advice for TinaCMS is to also understand this phenomena, so it could grow beyond a small technical user base and be used as the next WordPress, because WordPress has become a drag on everybody and I really want an easy CMS to succeed. For example I also found an alternative which is trying to do something similar to TinaCMS, which is called Keystatic and they seem to have referential integrity built-in.

My only hope is that we can ditch WordPress in the future and that a simple CMS succeeds and preferably with plugin support in the future.

At this point I’m writing my dream scenario 😅😂