Documentation/content/codeberg-pages/troubleshooting.md

---
eleventyNavigation:
  key: Troubleshooting
  title: Troubleshooting
  parent: CodebergPages
  order: 99
---

## My web browser displays a security warning when I try to access my Codeberg Pages

If your user name or repository name contains a dot, your Codeberg Pages URL (<https://user.name.codeberg.page>
or <https://repo.sitory.username.codeberg.page>)
contains a sub-sub-domain which does not work with Let's Encrypt wildcard certificates.
Use the alternative URL <https://pages.codeberg.org/user.name/> as a workaround or rename you repository
(e.g. replace `.` by `_`).

## My content is not updated

The Codeberg Pages v2 server caches files under a certain size (currently 1 MiB).
Please wait a few minutes until the cache has been invalidated.
This is done to improve performance, reduce cost and server load, and save energy.

## Cloudflare and Codeberg Pages

It is important that when you use [Cloudflare](https://cloudflare.com) to manage your Domain's DNS records,
that every DNS record used for Codeberg Pages needs to be set to **DNS only** (Have a gray cloud).
This ensures that Codeberg pages can properly handle everything necessary for your site such as SSL-Certificate and
redirects from other (sub-)domains.

## Troubleshooting post-git-pages errors

Given that Codeberg has moved to [git-pages](https://git-pages.org/) entirely, some behaviors changed.
Some things broke.
Including some undocumented behaviors website authors depended on.
This needs troubleshooting.
Luckily, git-pages allows troubleshooting.

Say, we add this (broken) [redirect rule](/codeberg-pages/advanced-usage/#redirects) to simulate old pages server redirection to `.html` pages:

```
/*/ /:splat.html 301
```

After committing it and opening a page like `https://example.org/hello`, we are redirected to a 404 page.
Something must be broken in redirects.
However, we don’t know that for sure.
Need to check.

There are two ways to find out what’s broken in the website:

```
# Plain web request
curl https://example.org/.git-pages/manifest.json
# Or a dedicated tool from git-pages
git-pages-cli --debug-manifest https://example.org
```

In either case, you get huge JSONs with meta-information about the website.
The structure is roughly:

```json
{
  "repoUrl": "https://codeberg.org/.../pages.git",
  "branch": "pages",
  "commit": "abcdef...",
  "contents": {
    "": {
      "type": "Directory"
    },
    ".domains": {
      // ...
    },
    ".gitignore": {
      // ...
    },
    "assets": {
      "type": "Directory"
    },
    "assets/...png": {
      "type": "ExternalFile",
      "originalSize": "...",
      "compressedSize": "...",
      "data": "...",
      "transform": "Identity",
      "contentType": "image/png",
      "gitHash": "..."
    },
    "index.html": {
      "type": "ExternalFile",
      "originalSize": "...",
      "compressedSize": "...",
      "data": "...",
      "transform": "Zstd",
      "contentType": "text/html; charset=utf-8",
      "gitHash": "..."
    }
    // ...
  },
  "originalSize": "...",
  "compressedSize": "...",
  "storedSize": "...",
  "redirects": [
    {
      "from": "/foo",
      "to": "/bar",
      "status": 301,
      "force": false
    }
    // ...
  ],
  "headers": [],
  "basicAuth": [],
  "problems": [
    {
      "path": "_redirects",
      "cause": "rule #1 \"/*/ /:splat.html 301\": splat * must be its own final segment of the path"
    }
  ]
}
```

And here’s the problem, under the `"problems"` key: the redirect is malformed!
In the end, this is one of the [changes and deprecations](/codeberg-pages/migrating-from-pages-v2/#breaking-changes-and-deprecations) that happened in migration.
But lamenting that is a story for another time.
Problem diagnosed through the useful git-pages manifest!
Use it to diagnose errors from now on!