[{"data":1,"prerenderedAt":20},["ShallowReactive",2],{"clay-page:\u002F4.x\u002Fguides\u002Ftroubleshooting":3},{"html":4,"toc":5,"description":16,"hero":17,"list":18,"socialImage":19},"\u003Ch1 id=\"troubleshooting\">Troubleshooting\u003C\u002Fh1>\n\u003Cp>Open the problem you have.\u003C\u002Fp>\n\u003Ch2 id=\"the-published-site\">\u003Ca class=\"heading-anchor\" href=\"#the-published-site\" aria-label=\"Link to this section\" data-route=\"#the-published-site\">#\u003C\u002Fa>The published site\u003C\u002Fh2>\n\u003Cdetails class=\"clay-details collapse\">\u003Csummary class=\"collapse-title\">\u003Cspan class=\"clay-details-icon\" aria-hidden=\"true\">\u003Ci class=\"fa-solid fa-chevron-right\">\u003C\u002Fi>\u003C\u002Fspan>\u003Cspan class=\"clay-details-title\">The site has no styles, or links lead to 404\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cdiv class=\"collapse-content\">\u003Cp>The site is served under a path, but Clay built it for the root. Set \u003Ccode>baseURL\u003C\u002Fcode> to that path, with slashes on both sides:\u003C\u002Fp>\n\u003Cdiv class=\"code-block has-title\">\u003Cdiv class=\"code-title\">\u003Ci class=\"fa-regular fa-file-lines\" aria-hidden=\"true\">\u003C\u002Fi>\u003Cspan>clay.yaml\u003C\u002Fspan>\u003C\u002Fdiv>\u003Cpre class=\"shiki shiki-themes light-plus dark-plus\" style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4;--shiki-light-bg:#FFFFFF;--shiki-dark-bg:#1E1E1E\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#800000;--shiki-dark:#569CD6\">baseURL\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4\">: \u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#A31515;--shiki-dark:#CE9178\">\"\u002Fmy-project\u002F\"\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\u003Cbutton type=\"button\" class=\"copy-code btn btn-sm btn-square btn-ghost\" title=\"Copy code\" aria-label=\"Copy code\">\u003Ci class=\"fa-solid fa-copy\">\u003C\u002Fi>\u003C\u002Fbutton>\u003C\u002Fdiv>\n\u003Cp>Check it with \u003Ccode>npx clay preview\u003C\u002Fcode>: it serves the site under its \u003Ccode>baseURL\u003C\u002Fcode>, like the host does.\u003C\u002Fp>\n\u003C\u002Fdiv>\u003C\u002Fdetails>\n\u003Cdetails class=\"clay-details collapse\">\u003Csummary class=\"collapse-title\">\u003Cspan class=\"clay-details-icon\" aria-hidden=\"true\">\u003Ci class=\"fa-solid fa-chevron-right\">\u003C\u002Fi>\u003C\u002Fspan>\u003Cspan class=\"clay-details-title\">Images do not show\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cdiv class=\"collapse-content\">\u003Cp>Reference images relative to the page, like \u003Ccode>img\u002Fscreen.png\u003C\u002Fcode> or \u003Ccode>..\u002Fimg\u002Fscreen.png\u003C\u002Fcode>. Paths starting with \u003Ccode>\u002F\u003C\u002Fcode> point to the root of the domain, not to your docs, and break under a \u003Ccode>baseURL\u003C\u002Fcode>. \u003Ccode>npx clay build\u003C\u002Fcode> reports images that do not exist.\u003C\u002Fp>\n\u003C\u002Fdiv>\u003C\u002Fdetails>\n\u003Cdetails class=\"clay-details collapse\">\u003Csummary class=\"collapse-title\">\u003Cspan class=\"clay-details-icon\" aria-hidden=\"true\">\u003Ci class=\"fa-solid fa-chevron-right\">\u003C\u002Fi>\u003C\u002Fspan>\u003Cspan class=\"clay-details-title\">\"Last updated\" is missing\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cdiv class=\"collapse-content\">\u003Cp>Clay reads the dates from git. Either the docs are not in a git repository, or CI checked out only the last commit.\u003C\u002Fp>\n\u003Cdiv class=\"clay-tabs\" data-tabs=\"\">\u003Cdiv role=\"tablist\" class=\"tabs tabs-border not-prose\">\u003Cbutton type=\"button\" role=\"tab\" id=\"clay-tabs-1-0\" class=\"tab tab-active\" aria-controls=\"clay-tabs-1-0-panel\" aria-selected=\"true\" tabindex=\"0\">GitHub Actions\u003C\u002Fbutton>\u003Cbutton type=\"button\" role=\"tab\" id=\"clay-tabs-1-1\" class=\"tab\" aria-controls=\"clay-tabs-1-1-panel\" aria-selected=\"false\" tabindex=\"-1\">GitLab CI\u003C\u002Fbutton>\u003C\u002Fdiv>\u003Cdiv role=\"tabpanel\" id=\"clay-tabs-1-0-panel\" class=\"clay-tab-panel\" aria-labelledby=\"clay-tabs-1-0\" data-label=\"GitHub Actions\">\u003Cdiv class=\"code-block\">\u003Cpre class=\"shiki shiki-themes light-plus dark-plus\" style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4;--shiki-light-bg:#FFFFFF;--shiki-dark-bg:#1E1E1E\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4\">- \u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#800000;--shiki-dark:#569CD6\">uses\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4\">: \u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#0000FF;--shiki-dark:#CE9178\">actions\u002Fcheckout@v7\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#800000;--shiki-dark:#569CD6\">  with\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4\">:\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#800000;--shiki-dark:#569CD6\">    fetch-depth\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4\">: \u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#076240;--shiki-dark:#B5CEA8\">0\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\u003Cbutton type=\"button\" class=\"copy-code btn btn-sm btn-square btn-ghost\" title=\"Copy code\" aria-label=\"Copy code\">\u003Ci class=\"fa-solid fa-copy\">\u003C\u002Fi>\u003C\u002Fbutton>\u003C\u002Fdiv>\n\u003C\u002Fdiv>\u003Cdiv role=\"tabpanel\" id=\"clay-tabs-1-1-panel\" class=\"clay-tab-panel\" aria-labelledby=\"clay-tabs-1-1\" data-label=\"GitLab CI\" hidden=\"\">\u003Cdiv class=\"code-block\">\u003Cpre class=\"shiki shiki-themes light-plus dark-plus\" style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4;--shiki-light-bg:#FFFFFF;--shiki-dark-bg:#1E1E1E\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#800000;--shiki-dark:#569CD6\">variables\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4\">:\u003C\u002Fspan>\u003C\u002Fspan>\n\u003Cspan class=\"line\">\u003Cspan style=\"--shiki-light:#800000;--shiki-dark:#569CD6\">  GIT_DEPTH\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4\">: \u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#076240;--shiki-dark:#B5CEA8\">0\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\u003Cbutton type=\"button\" class=\"copy-code btn btn-sm btn-square btn-ghost\" title=\"Copy code\" aria-label=\"Copy code\">\u003Ci class=\"fa-solid fa-copy\">\u003C\u002Fi>\u003C\u002Fbutton>\u003C\u002Fdiv>\n\u003C\u002Fdiv>\u003C\u002Fdiv>\n\u003C\u002Fdiv>\u003C\u002Fdetails>\n\u003Cdetails class=\"clay-details collapse\">\u003Csummary class=\"collapse-title\">\u003Cspan class=\"clay-details-icon\" aria-hidden=\"true\">\u003Ci class=\"fa-solid fa-chevron-right\">\u003C\u002Fi>\u003C\u002Fspan>\u003Cspan class=\"clay-details-title\">Icons are missing or show as squares\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cdiv class=\"collapse-content\">\u003Cul>\n\u003Cli>Check the icon’s classes on \u003Ca href=\"https:\u002F\u002Ffontawesome.com\u002Ficons\" target=\"_blank\" rel=\"noopener noreferrer\">\u003Ci class=\"fa-solid fa-arrow-up-right-from-square clay-external-icon\" aria-hidden=\"true\">\u003C\u002Fi>fontawesome.com\u003C\u002Fa>: both the style and the name are needed, \u003Ccode>fa-solid fa-rocket\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>Pro icons only work with a \u003Ca href=\"\u002Fclay-example-repo\u002F4.x\u002Ffeatures\u002Fthemes-and-icons#font-awesome-kits\" data-route=\"\u002F4.x\u002Ffeatures\u002Fthemes-and-icons#font-awesome-kits\">kit\u003C\u002Fa> that includes them.\u003C\u002Fli>\n\u003Cli>With a kit, add your site’s domain to the kit’s allowed domains in your Font Awesome account.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003C\u002Fdiv>\u003C\u002Fdetails>\n\u003Cdetails class=\"clay-details collapse\">\u003Csummary class=\"collapse-title\">\u003Cspan class=\"clay-details-icon\" aria-hidden=\"true\">\u003Ci class=\"fa-solid fa-chevron-right\">\u003C\u002Fi>\u003C\u002Fspan>\u003Cspan class=\"clay-details-title\">Opening index.html directly looks broken\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cdiv class=\"collapse-content\">\u003Cp>The site needs a web server: opened from disk (\u003Ccode>file:\u002F\u002F…\u003C\u002Fcode>), the browser cannot load its styles, scripts and search. Use \u003Ccode>npx clay preview\u003C\u002Fcode>.\u003C\u002Fp>\n\u003C\u002Fdiv>\u003C\u002Fdetails>\n\u003Ch2 id=\"building-and-previewing\">\u003Ca class=\"heading-anchor\" href=\"#building-and-previewing\" aria-label=\"Link to this section\" data-route=\"#building-and-previewing\">#\u003C\u002Fa>Building and previewing\u003C\u002Fh2>\n\u003Cdetails class=\"clay-details collapse\">\u003Csummary class=\"collapse-title\">\u003Cspan class=\"clay-details-icon\" aria-hidden=\"true\">\u003Ci class=\"fa-solid fa-chevron-right\">\u003C\u002Fi>\u003C\u002Fspan>\u003Cspan class=\"clay-details-title\">The build fails on a page\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cdiv class=\"collapse-content\">\u003Cp>Clay shows which page failed and why. Common causes:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>A link in raw HTML\u003C\u002Fstrong> points to a page that does not exist. The link check only sees Markdown links; fix the HTML link.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Front matter\u003C\u002Fstrong> is not closed: the second \u003Ccode>---\u003C\u002Fcode> line is missing.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Run \u003Ccode>npx clay build --verbose\u003C\u002Fcode> for the complete output.\u003C\u002Fp>\n\u003C\u002Fdiv>\u003C\u002Fdetails>\n\u003Cdetails class=\"clay-details collapse\">\u003Csummary class=\"collapse-title\">\u003Cspan class=\"clay-details-icon\" aria-hidden=\"true\">\u003Ci class=\"fa-solid fa-chevron-right\">\u003C\u002Fi>\u003C\u002Fspan>\u003Cspan class=\"clay-details-title\">\"clay dev\" is running for this project\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cdiv class=\"collapse-content\">\u003Cp>A build and the dev server cannot run in the same project at the same time. Stop \u003Ccode>clay dev\u003C\u002Fcode> (\u003Ckbd>Ctrl\u003C\u002Fkbd> + \u003Ckbd>C\u003C\u002Fkbd> in its terminal), then build again.\u003C\u002Fp>\n\u003C\u002Fdiv>\u003C\u002Fdetails>\n\u003Cdetails class=\"clay-details collapse\">\u003Csummary class=\"collapse-title\">\u003Cspan class=\"clay-details-icon\" aria-hidden=\"true\">\u003Ci class=\"fa-solid fa-chevron-right\">\u003C\u002Fi>\u003C\u002Fspan>\u003Cspan class=\"clay-details-title\">Changes do not show up in clay dev\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cdiv class=\"collapse-content\">\u003Cp>\u003Ccode>clay dev\u003C\u002Fcode> reloads the browser when a page, an image or \u003Ccode>clay.yaml\u003C\u002Fcode> changes. If nothing happens, check that you edit the files of the project \u003Ccode>clay dev\u003C\u002Fcode> was started in, and look at its output for errors.\u003C\u002Fp>\n\u003C\u002Fdiv>\u003C\u002Fdetails>\n\u003Cdetails class=\"clay-details collapse\">\u003Csummary class=\"collapse-title\">\u003Cspan class=\"clay-details-icon\" aria-hidden=\"true\">\u003Ci class=\"fa-solid fa-chevron-right\">\u003C\u002Fi>\u003C\u002Fspan>\u003Cspan class=\"clay-details-title\">The port is in use\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cdiv class=\"collapse-content\">\u003Cp>Another program uses port 3000 (or 4173 for \u003Ccode>clay preview\u003C\u002Fcode>). Choose another one:\u003C\u002Fp>\n\u003Cdiv class=\"code-block is-terminal has-bar\">\u003Cdiv class=\"code-terminal\" aria-hidden=\"true\">\u003Cspan>\u003C\u002Fspan>\u003Cspan>\u003C\u002Fspan>\u003Cspan>\u003C\u002Fspan>\u003C\u002Fdiv>\u003Cpre class=\"shiki shiki-themes light-plus dark-plus\" style=\"--shiki-light:#000000;--shiki-dark:#D4D4D4;--shiki-light-bg:#FFFFFF;--shiki-dark-bg:#1E1E1E\" tabindex=\"0\">\u003Ccode>\u003Cspan class=\"line command\">\u003Cspan style=\"--shiki-light:#695221;--shiki-dark:#DCDCAA\">npx\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#A31515;--shiki-dark:#CE9178\"> clay\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#A31515;--shiki-dark:#CE9178\"> dev\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#0000FF;--shiki-dark:#569CD6\"> --port\u003C\u002Fspan>\u003Cspan style=\"--shiki-light:#076240;--shiki-dark:#B5CEA8\"> 3001\u003C\u002Fspan>\u003C\u002Fspan>\u003C\u002Fcode>\u003C\u002Fpre>\u003Cbutton type=\"button\" class=\"copy-code btn btn-sm btn-square btn-ghost\" title=\"Copy code\" aria-label=\"Copy code\">\u003Ci class=\"fa-solid fa-copy\">\u003C\u002Fi>\u003C\u002Fbutton>\u003C\u002Fdiv>\n\u003C\u002Fdiv>\u003C\u002Fdetails>\n\u003Cdetails class=\"clay-details collapse\">\u003Csummary class=\"collapse-title\">\u003Cspan class=\"clay-details-icon\" aria-hidden=\"true\">\u003Ci class=\"fa-solid fa-chevron-right\">\u003C\u002Fi>\u003C\u002Fspan>\u003Cspan class=\"clay-details-title\">Node.js is too old\u003C\u002Fspan>\u003C\u002Fsummary>\u003Cdiv class=\"collapse-content\">\u003Cp>Clay needs Node.js 20.19 or newer. Check with \u003Ccode>node --version\u003C\u002Fcode>, and update Node.js from \u003Ca href=\"https:\u002F\u002Fnodejs.org\" target=\"_blank\" rel=\"noopener noreferrer\">\u003Ci class=\"fa-solid fa-arrow-up-right-from-square clay-external-icon\" aria-hidden=\"true\">\u003C\u002Fi>nodejs.org\u003C\u002Fa> or with your version manager.\u003C\u002Fp>\n\u003C\u002Fdiv>\u003C\u002Fdetails>\n\u003Ch2 id=\"still-stuck\">\u003Ca class=\"heading-anchor\" href=\"#still-stuck\" aria-label=\"Link to this section\" data-route=\"#still-stuck\">#\u003C\u002Fa>Still stuck?\u003C\u002Fh2>\n\u003Cp>A coding agent can often find the cause; describe the problem where the prompt says so:\u003C\u002Fp>\n\u003Cdiv class=\"clay-prompt-aura aura not-prose\">\u003Cdiv class=\"clay-prompt code-block\">\u003Cdiv class=\"clay-prompt-title\">\u003Ci class=\"fa-solid fa-wand-magic-sparkles\" aria-hidden=\"true\">\u003C\u002Fi>\u003Cspan>Suggested prompt\u003C\u002Fspan>\u003C\u002Fdiv>\u003Cpre class=\"clay-prompt-text\">My Clay site has a problem: <describe it>. Read\nhttps:\u002F\u002Fclay-doc.github.io\u002Fclay-example-repo\u002Fguides\u002Ftroubleshooting.md and\nhttps:\u002F\u002Fclay-doc.github.io\u002Fclay-example-repo\u002Fpublishing\u002Fbuild-checks.md, run\n`npx clay build --strict`, find the cause and fix it.\u003C\u002Fpre>\u003Cbutton type=\"button\" class=\"copy-code btn btn-sm btn-square btn-ghost\" title=\"Copy prompt\" aria-label=\"Copy prompt\">\u003Ci class=\"fa-solid fa-copy\">\u003C\u002Fi>\u003C\u002Fbutton>\u003C\u002Fdiv>\u003C\u002Fdiv>\n\u003Cp>Otherwise, open an issue in the \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fclay-doc\u002Fclay\u002Fissues\" target=\"_blank\" rel=\"noopener noreferrer\">\u003Ci class=\"fa-solid fa-arrow-up-right-from-square clay-external-icon\" aria-hidden=\"true\">\u003C\u002Fi>Clay repository\u003C\u002Fa> with the command you ran and its output.\u003C\u002Fp>\n",[6,10,13],{"id":7,"text":8,"level":9},"the-published-site","The published site",2,{"id":11,"text":12,"level":9},"building-and-previewing","Building and previewing",{"id":14,"text":15,"level":9},"still-stuck","Still stuck?","Solutions for the most common problems with Clay sites, from missing styles to missing dates.",null,false,"\u002F_clay\u002Fsocial\u002F4.x\u002Fguides\u002Ftroubleshooting.png",1792666369672]