Troubleshooting

This guide provides solutions to common issues you may encounter while using Sveltia CMS.

Fixing a Blank Page Caused by Rocket Loader

Cloudflare’s Rocket Loader content optimizer is known to interfere with Sveltia CMS’s JavaScript code, resulting in a blank page. If you are using Cloudflare and have Rocket Loader enabled, you may need to disable it by adding the data-cfasync="false" attribute to the script tag that loads Sveltia CMS from the CDN:

<script data-cfasync="false" src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>

See discussion #552 for details.

Working Around an Authentication Error

If you get an “Authentication Aborted” error when trying to sign in to GitHub, GitLab or Gitea/Forgejo using the authorization code flow, you may need to check your site’s Cross-Origin-Opener-Policy. The COOP header is not widely used, but it’s known to break the OAuth flow with a popup window. If that’s your case, changing same-origin to same-origin-allow-popups solves the problem.

See issue #131 for details.

Avoiding API Issues with Reverse Proxy Servers

When using a self-hosted Git service like Gitea or Forgejo, it’s common to use a reverse proxy server such as Nginx or Apache to handle incoming requests. However, certain configurations of the reverse proxy can interfere with API requests made by Sveltia CMS, leading to unexpected errors.

One known issue is the double-encoding of special characters in file paths. This can happen if the reverse proxy is not configured to properly forward requests to the Git service. To avoid this issue, make sure to review your reverse proxy settings and ensure that URL encoding is handled correctly.

See issue #469 for details.

Using Proper Naming Conventions

In the CMS configuration, you must define the name option for collections, collections files, fields and variable types. These names have to be unique within their scope and cannot contain certain special characters.

Invalid characters include spaces as well as dots (.) and asterisks (*), which are used to denote nested structures and wildcards, respectively, especially for the Relation field type’s field references. If you use invalid names, the CMS will show config validation errors on the login screen.

For example, the following configuration is invalid because the field name foo.bar contains a dot:

fields:
  - name: foo.bar
    widget: object
    fields:
      - name: enabled
        widget: boolean

To fix this, you should use nested objects instead:

fields:
  - name: foo
    widget: object
    fields:
      - name: bar
        widget: object
        fields:
          - name: enabled
            widget: boolean

See discussion #542 for details.