Astro Static Route 404 Behind Caddy: Align build.format and Trailing Slashes

Inspect the generated path first#

Build the site and compare the failing URL with the actual files:

1
pnpm build
2
find dist -maxdepth 3 -type f | sort

Astro’s configuration reference defines these formats:

The default format is directory. Astro recommends pairing it with trailingSlash: 'always'; file pairs with trailingSlash: 'never'. For prerendered pages, the hosting server handles the final slash behavior, so a successful astro dev or astro preview request does not prove that Caddy will resolve the production path.

Use a consistent Astro configuration#

For a static site whose public URLs end in /, make the contract explicit:

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  output: 'static',
5
  trailingSlash: 'always',
6
  build: {
7
    format: 'directory',
8
  },
9
});

This does not create redirects for a prerendered page by itself. It makes Astro generate a directory-shaped artifact and keeps development URLs aligned with the intended production shape. Your static server still needs to serve directories and their index.html files.

If you deliberately use build.format: 'file', do not expect /guide/ to find dist/guide.html. Either publish the extension-bearing URL or add a tested, explicit rewrite for the extensionless route. Switching to directory output is usually easier to reason about for a Caddy static site.

Point Caddy at the actual dist root#

The Caddy root must be the directory containing the generated files, not the repository parent or a directory that contains a second dist folder:

1
example.com {
2
    root * /usr/share/caddy
3
    file_server
4
}

In a container, copy the contents of dist into /usr/share/caddy:

1
FROM caddy:2-alpine
2
COPY dist/ /usr/share/caddy/

The existing Astro static site Docker and Caddy guide covers the multi-stage build boundary. This article focuses on the route contract after the files reach the server.

When the request is /guide/, Caddy’s static file server can resolve the directory and its index file. If you use try_files elsewhere in the site, Caddy’s documented directory form includes the trailing slash:

1
try_files {path} {path}/ =404

Do not replace a pre-rendered site’s real 404 handling with try_files {path} /index.html unless a client-side SPA router owns every unmatched route. That fallback can make a broken Astro path appear to work while returning the wrong document and canonical URL.

Test both slash variants and a real 404#

Run the checks against the same container or host configuration that serves production:

1
curl --head http://localhost:8080/guide/
2
curl --head http://localhost:8080/guide
3
curl --head http://localhost:8080/does-not-exist/

Interpret the results with the generated tree:

• /guide/ should serve dist/guide/index.html for directory output.
• /guide may redirect, depending on the server configuration; it should not be silently rewritten to an unrelated page.
• A missing route should remain a real 404 rather than being swallowed by an SPA fallback.

If the site is deployed below a subpath such as /docs, also set Astro’s base option and verify that assets are copied under that prefix. A correct Caddy root cannot compensate for links generated with the wrong base path.

FAQ#