Grist “No example workspace available” Error

I’m writing this post since I’ve been managing a self-hosted Grist instance for a while now. Grist is essentially a self-hosted version of Airtable, but even more supercharged! It’s a great product, but it’s still in its infancy and so community support resources are quite sparse.

I was trying to upgrade my Grist instance which I had previously set up according to the instructions from Grist themselves. Upon swapping the Docker image version and creating a new Docker container, I kept seeing the following error that was preventing the container from starting:

Error: No example workspace available
    at HomeDBManager.initializeSpecialIds (/grist/_build/app/gen-server/lib/HomeDBManager.js:239:23)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async FlexServer.initHomeDBManager (/grist/_build/app/server/lib/FlexServer.js:607:9)
    at async main (/grist/_build/app/server/mergedServerMain.js:98:5)
    at async main (/grist/_build/stubs/app/server/server.js:144:20)

The only reference I could find about this error on the internet was a thread on the Grist forum. Unfortunately, the problem in that case was database corruption, which didn’t apply to my case – I verified that my database was intact by comparing it with my backups.

After looking in the Grist source code (this is why open source is good!), it turns out this exception is thrown in a method that (for some reason) verifies the existence of a workspace in an organization owned by the built-in “Support user”. The workspace, organization, and built-in support user are all automatically created by the database migrations on first run. This was the important clue that helped me decipher the issue. It turns out the .initializeSpecialIds method referenced in the traceback searches the Grist database’s users table for a support user, finds its related org, and then looks for a workspace owned by that org. This support user should normally be the built-in one, which would allow the Grist server to start up successfully, but it turns out I had actually changed who this user is by setting the GRIST_SUPPORT_EMAIL environment variable. The user I had set as the GRIST_SUPPORT_EMAIL did not own a workspace, causing the error I saw.

So, the solution: clear the value of the GRIST_SUPPORT_EMAIL environment variable. This will make the .initializeSpecialIds method look for a workspace managed by the built in “Support user”, rather than look for a workspace owned by your custom GRIST_SUPPORT_EMAIL user (which may not exist, as was true in my case).