DioxusLabs/dioxus · error

Failed to read index.html from public directory

Error message

Failed to read index.html from public directory

What it means

When the fullstack server boots its RenderedServerConfig it looks for index.html under the public directory; if the file exists but read_to_string fails (invalid UTF-8 bytes or a read error like permissions), it panics with this expect during server construction.

Source

Thrown at packages/fullstack-server/src/config.rs:61

    /// Create a new ServeConfig with incremental static generation disabled and the default index.html settings.
    pub fn builder() -> Self {
        Self::new()
    }

    /// Create a new ServeConfig with incremental static generation disabled and the default index.html settings
    ///
    /// This will automatically use the `index.html` file in the `/public` directory if it exists.
    /// The `/public` folder is meant located next to the current executable. If no `index.html` file is found,
    /// a default index.html will be used, which will not include any JavaScript or WASM initialization code.
    ///
    /// To provide an alternate `index.html`, you can use `with_index_html` method instead.
    pub fn new() -> Self {
        let index = if let Some(public_path) = crate::public_path() {
            let index_html_path = public_path.join("index.html");

            if index_html_path.exists() {
                let index_html = std::fs::read_to_string(index_html_path)
                    .expect("Failed to read index.html from public directory");

                IndexHtml::new(&index_html, "main")
                    .expect("Failed to parse index.html from public directory")
            } else {
                IndexHtml::ssr_only()
            }
        } else {
            tracing::warn!(
                "Cannot identify public directory, using default index.html. If you need client-side scripts (like JS + WASM), please provide an explicit public directory."
            );
            IndexHtml::ssr_only()
        };

        Self {
            index,
            incremental: None,
            context_providers: Default::default(),
            streaming_mode: StreamingMode::default(),

View on GitHub (pinned to 393d190a80)

Solutions

1. Re-save public/index.html as UTF-8
2. Fix permissions/ownership so the server process can read the file (chown/chmod in containers)
3. If the file is not meant to be served, remove or rename it so the SSR-only default index is used

Example fix

# before: file saved as latin-1 with invalid bytes
# fix: convert encoding to UTF-8
iconv -f latin1 -t utf-8 public/index.html -o public/index.html

// Validate index.html before starting the fullstack server
let path = std::path::Path::new("public/index.html");
if path.exists() {
    let bytes = std::fs::read(path).expect("read index.html");
    std::str::from_utf8(&bytes).expect("index.html must be UTF-8");
}

fn is_utf8_file(p: &std::path::Path) -> bool {
    std::fs::read(p).map(|b| std::str::from_utf8(&b).is_ok()).unwrap_or(false)
}

When it happens

Trigger: A public/index.html that exists but is not valid UTF-8 (saved in a legacy codepage or containing stray binary bytes) or is unreadable by the server process when RenderedServerConfig::new() runs.

Common situations: Templates edited on Windows and saved as latin-1/ANSI; binary garbage pasted into index.html; container images where the public dir is root-owned while the server runs as another user.

Related errors

• Failed to parse index.html from public directory
• expected URL to be UTF-8 encoded
• input_path should be valid utf8
• Head element to exist
• Body element to exist

AI-assisted analysis of DioxusLabs/dioxus@393d190a80 (2026-08-16). Data as JSON: /api/errors/6c5e1327f5cc89e5. Report an issue: GitHub.