Troubleshooting
Astro provides several different tools to help you troubleshoot and debug your code.
Common Error Messages
Section titled Common Error MessagesHere are some common error messages you might see in the terminal, what they might mean, and what to do about them.
Cannot use import statement outside a module
Section titled Cannot use import statement outside a moduleIn Astro components, <script>
tags are hoisted and loaded as JS modules by default. If you have included the is:inline
directive or any other attribute in your tag, this default behavior is removed.
Solution: If you have added any attributes to your <script>
tag, you must also add the type="module"
attribute to be able to use import statements.
Status: Expected Astro behavior, as intended.
Not sure that this is your problem?
Check to see if anyone else has reported this issue!
document
(or window
) is not defined
Section titled document (or window) is not definedThis error occurs when trying to access document
or window
on the server.
Astro components run on the server, so you can’t access these browser-specific objects within the frontmatter.
Framework components run on the server by default, so this error can occur when accessing document
or window
during rendering.
Solution: Determine the code that calls document
or window
. If you aren’t using document
or window
directly and still getting this error, check to see if any packages you’re importing are meant to run on the client.
-
If the code is in an Astro component, move it to a
<script>
tag outside of the frontmatter. This tells Astro to run this code on the client, wheredocument
andwindow
are available. -
If the code is in a framework component, try to access these objects after rendering using lifecycle methods (e.g.
useEffect()
in React,onMounted()
in Vue, andonMount()
in Svelte). You can also prevent the component from rendering on the server at all by adding theclient:only
directive.
Status: Expected Astro behavior, as intended.
Expected a default export
Section titled Expected a default exportThis error can be thrown when trying to import or render an invalid component, or one that is not working properly. (This particular message occurs because of the way importing a UI component works in Astro.)
Solution: Try looking for errors in any component you are importing and rendering, and make sure it’s working correctly. Consider opening an Astro starter template from astro.new and troubleshooting just your component in a minimal Astro project.
Status: Expected Astro behavior, as intended.
Refused to execute inline script
Section titled Refused to execute inline scriptYou may see the following error logged in the browser console:
Refused to execute inline script because it violates the following Content Security Policy directive: …
This means that your site’s Content Security Policy (CSP) disallows running inline <script>
tags, which Astro outputs by default.
Solution: Update your CSP to include script-src: 'unsafe-inline'
to allow inline scripts to run.
Common gotchas
Section titled Common gotchasMy component is not rendering
Section titled My component is not renderingFirst, check to see that you have imported the component in your .astro
component script or .mdx
file.
Then check your import statement:
-
Is your import linking to the wrong place? (Check your import path.)
-
Does your import have the same name as the imported component? (Check your component name and that it follows the
.astro
syntax.) -
Have you included the extension in the import? (Check that your imported file contains an extension. e.g.
.astro
,.md
,.vue
,.svelte
. Note: File extensions are not required for.js(x)
and.ts(x)
files only.)
My component is not interactive
Section titled My component is not interactiveIf your component is rendering (see above) but is not responding to user interaction, then you may be missing a client:*
directive to hydrate your component.
By default, a UI Framework component is not hydrated in the client. If no client:*
directive is provided, its HTML is rendered onto the page without JavaScript.
Cannot find package ‘X’
Section titled Cannot find package ‘X’If you see a "Cannot find package 'react'"
(or similar) warning when you start up Astro, that means that you need to install that package into your project. Not all package managers will install peer dependencies for you automatically. If you are on Node v16+ and using npm, you should not need to worry about this section.
React, for example, is a peer dependency of the @astrojs/react
integration. That means that you should install the official react
and react-dom
packages alongside your integration. The integration will then pull from these packages automatically.
# Example: Install integrations and frameworks together
npm install @astrojs/react react react-dom
See Astro’s integration guide for instructions on adding framework renderers, CSS tools and other packages to Astro.
Astro.glob()
- no matches found
Section titled Astro.glob() - no matches foundWhen using Astro.glob()
to import files, be sure to use the correct glob syntax that will match all the files you need.
Filepaths
Section titled FilepathsFor example, use ../components/**/*.js
in src/pages/index.astro
to import both of the following files:
src/components/MyComponent.js
src/components/includes/MyOtherComponent.js
Supported Values
Section titled Supported ValuesAstro.glob()
does not support dynamic variables and string interpolation.
This is not a bug in Astro. It is due to a limitation of Vite’s import.meta.glob()
function which only supports static string literals.
A common workaround is to instead import a larger set of files that includes all the files you need using Astro.glob()
, then filter them:
---
const { postSlug } = Astro.props;
const pathToMyFeaturedPost = `src/pages/blog/${postSlug}.md`;
const posts = await Astro.glob('../pages/blog/*.md');
const myFeaturedPost = posts.find(post => post.file.includes(pathToMyFeaturedPost));
---
<p>
Take a look at my favorite post, <a href={myFeaturedPost.url}>{myFeaturedPost.frontmatter.title}</a>!
</p>
Using Astro with Yarn 2+ (Berry)
Section titled Using Astro with Yarn 2+ (Berry)Yarn 2+, a.k.a. Berry, uses a technique called Plug’n’Play (PnP) to store and manage Node modules, which can cause problems while initializing a new Astro project using create astro
or while working with Astro. A workaround is to set the nodeLinker
property in .yarnrc.yml
to node-modules
:
nodeLinker: "node-modules"
Using <head>
in a component
Section titled Using <head> in a componentIn Astro, using a <head>
tag works like any other HTML tag: it does not get moved to the top of the page or merged with the existing <head>
. Because of this, you usually only want to include one <head>
tag throughout a page. We recommend writing that single <head>
and its contents in a layout component.
An unexpected <script>
or <style>
is included
Section titled An unexpected <script> or <style> is includedYou may notice an imported component’s <script>
or <style>
tags included in your HTML source even if that component doesn’t appear in the final output. For example, this will occur with conditionally rendered components that are not displayed.
Astro’s build process works on the module graph: once a component is included in the template, its <script>
and <style>
tags are processed, optimized, and bundled, whether it appears in the final output or not. This does not apply to scripts when the is:inline
directive is applied.
Tips and tricks
Section titled Tips and tricksDebugging with console.log()
Section titled Debugging with console.log()console.log()
is a simple-but-popular method of debugging your Astro code. Where you write your console.log
statement will determine where your debugging output is printed.
Frontmatter
Section titled FrontmatterA console.log()
statement in Astro frontmatter will always output to the terminal running the Astro CLI. This is because Astro runs on the server, and never in the browser.
---
const sum = (a, b) => a + b;
// Example: Outputs "4" to the CLI terminal
console.log(sum(2, 2));
---
JS scripts
Section titled JS scriptsCode that is written or imported inside of an Astro <script>
tag is run in the browser. Any console.log()
statements or other debug output will be printed to the console in your browser.
Debugging framework components
Section titled Debugging framework componentsFramework components (like React and Svelte) are unique: They render server-side by default, meaning that console.log()
debug output will be visible in the terminal. However, they can also be hydrated for the browser, which may cause your debug logs to also appear in the browser.
This can be useful for debugging differences between the SSR output and the hydrated components in the browser.
Astro <Debug />
component
Section titled Astro <Debug /> componentTo help you debug your Astro components, Astro provides a built-in <Debug />
component which renders any value directly into your component HTML template. This is useful for quick debugging in the browser without having to flip back-and-forth between your terminal and your browser.
---
import { Debug } from 'astro/components';
const sum = (a, b) => a + b;
---
<!-- Example: Outputs {answer: 6} to the browser -->
<Debug answer={sum(2, 4)} />
The Debug component supports a variety of syntax options for even more flexible and concise debugging:
---
import { Debug } from 'astro/components';
const sum = (a, b) => a + b;
const answer = sum(2, 4);
---
<!-- Example: All three examples are equivalent. -->
<Debug answer={sum(2, 4)} />
<Debug {{answer: sum(2, 4)}} />
<Debug {answer} />
Need more?
Section titled Need more?Come and chat with us on Discord and explain your issue in the #support-threads
channel. We’re always happy to help!
Visit the current open Issues in Astro to see if you are encountering a known problem or file a bug report.
You can also visit RFC Discussions to see whether you’ve found a known limitation of Astro, and check to see whether there are current proposals related to your use case.