Trouble Shooting Guide

Common Issues and how to fix them

Troubleshooting

Site Not Loading

Check these:

  1. Repository has both .pages file and public/ folder
  2. .pages has enabled: true
  3. Repository is public (or admin configured private repo access)
  4. You’re visiting the correct URL pattern

Get the URL pattern:

https://{your-username}.{pages-domain}/{repository-name}/

Custom Domain Not Working

Step-by-step checklist:

  1. DNS record points to the correct IP (check with dig www.yoursite.com)
  2. .pages file has custom_domain: www.yoursite.com
  3. You visited your pages URL first to activate the domain
  4. Waited 5-15 minutes for DNS propagation
  5. Waited 2-3 minutes for SSL certificate generation

Still not working?

# Check DNS propagation:
dig www.yoursite.com

# Should show:
www.yoursite.com.  300  IN  A  123.456.789.012

Wait longer if the IP is wrong or missing.

Password Not Working

Common issues:

  1. Used the plain password in .pages instead of the SHA256 hash
  2. Extra spaces or newlines in the hash
  3. Cache hasn’t refreshed yet (wait 60 seconds)

Regenerate the hash:

echo -n "yourpassword" | shasum -a 256

Copy the entire hash (64 characters) into .pages.

Redirects Not Loading

Checklist:

  1. .redirects file is in repository root (not in public/)
  2. Custom domain is configured in .pages
  3. You visited /LOAD_REDIRECTS endpoint
  4. Format is correct: FROM:TO (one per line)
  5. No empty lines or spaces around colons

Reload redirects:

curl https://www.yoursite.com/LOAD_REDIRECTS

Files Not Updating

Your changes are probably cached. Wait 5 minutes (default cache TTL), then check again. If urgent, ask your admin to flush the cache.

Tips and Tricks

In your HTML, use relative links so they work on both pages.example.com and custom domains:

<!-- Good -->
<a href="/about/">About</a>
<img src="/images/logo.png" alt="Logo">

<!-- Bad (won't work on custom domains) -->
<a href="https://you.pages.example.com/repo/about/">About</a>

Deploy with CI/CD

Automate deployments with Forgejo Actions:

# .forgejo/workflows/deploy.yml
name: Deploy Site
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build site
        run: |
          npm install
          npm run build  # Outputs to public/
      - name: Commit
        run: |
          git config user.name "Bot"
          git config user.email "bot@example.com"
          git add public/
          git commit -m "Deploy: ${{ github.sha }}"
          git push