Error reference

The following reference is a complete list of the errors you may encounter while using Astro. For additional assistance, including common pitfalls, please also see our Troubleshooting Guide.

Astro.redirect is not available in static mode.

Section titled Astro.redirect is not available in static mode.

StaticRedirectNotAvailable: Redirects are only available when using output: 'server'. Update your Astro config if you need SSR features. (E03001)

The Astro.redirect function is only available when Server-side rendering is enabled.

To redirect on a static website, the meta refresh attribute can be used. Certain hosts also provide config-based redirects (ex: Netlify redirects).

See Also:

Astro.clientAddress is not available in current adapter.

Section titled Astro.clientAddress is not available in current adapter.

ClientAddressNotAvailable: Astro.clientAddress is not available in the ADAPTER_NAME adapter. File an issue with the adapter to add support. (E03002)

The adapter you.‘re using unfortunately does not support Astro.clientAddress.

See Also:

Astro.clientAddress is not available in static mode.

Section titled Astro.clientAddress is not available in static mode.

StaticClientAddressNotAvailable: Astro.clientAddress is only available when using output: 'server'. Update your Astro config if you need SSR features. (E03003)

The Astro.clientAddress property is only available when Server-side rendering is enabled.

To get the user’s IP address in static mode, different APIs such as Ipify can be used in a Client-side script or it may be possible to get the user’s IP using a serverless function hosted on your hosting provider.

See Also:

No static path found for requested path.

Section titled No static path found for requested path.

NoMatchingStaticPathFound: A getStaticPaths() route pattern was matched, but no matching static path was found for requested path PATH_NAME. (E03004)

A dynamic route was matched, but no corresponding path was found for the requested parameters. This is often caused by a typo in either the generated or the requested path.

See Also:

Invalid type returned by Astro page.

Section titled Invalid type returned by Astro page.

Route returned a RETURNED_VALUE. Only a Response can be returned from Astro files. (E03005)

Only instances of Response can be returned inside Astro files.

pages/login.astro
---
return new Response(null, {
 status: 404,
 statusText: 'Not found'
});

// Alternatively, for redirects, Astro.redirect also returns an instance of Response
return Astro.redirect('/login');
---

See Also:

Missing value for client:media directive.

Section titled Missing value for client:media directive.

MissingMediaQueryDirective: Media query not provided for client:media directive. A media query similar to client:media="(max-width: 600px)" must be provided (E03006)

A media query parameter is required when using the client:media directive.

<Counter client:media="(max-width: 640px)" />

See Also:

Unable to render COMPONENT_NAME. There are RENDERER_COUNT renderer(s) configured in your astro.config.mjs file, but none were able to server-side render COMPONENT_NAME. (E03007)

None of the installed integrations were able to render the component you imported. Make sure to install the appropriate integration for the type of component you are trying to include in your page.

For JSX / TSX files, @astrojs/react, @astrojs/preact or @astrojs/solid-js can be used. For Vue and Svelte files, the @astrojs/vue and @astrojs/svelte integrations can be used respectively

See Also:

No client entrypoint specified in renderer.

Section titled No client entrypoint specified in renderer.

NoClientEntrypoint: COMPONENT_NAME component has a client:CLIENT_DIRECTIVE directive, but no client entrypoint was provided by RENDERER_NAME. (E03008)

Astro tried to hydrate a component on the client, but the renderer used does not provide a client entrypoint to use to hydrate.

See Also:

Missing hint on client:only directive.

Section titled Missing hint on client:only directive.

NoClientOnlyHint: Unable to render COMPONENT_NAME. When using the client:only hydration strategy, Astro needs a hint to use the correct renderer. (E03009)

client:only components are not ran on the server, as such Astro does not know (and cannot guess) which renderer to use and require a hint. Like such:

<SomeReactComponent client:only="react" />

See Also:

Invalid value returned by a getStaticPaths path.

Section titled Invalid value returned by a getStaticPaths path.

InvalidGetStaticPathParam: Invalid params given to getStaticPaths path. Expected an object, got PARAM_TYPE (E03010)

The params property in getStaticPaths’s return value (an array of objects) should also be an object.

pages/blog/[id].astro
---
export async function getStaticPaths() {
  return [
    { params: { slug: "blog" } },
    { params: { slug: "about" } }
  ];
}
---

See Also:

Invalid value returned by getStaticPaths.

Section titled Invalid value returned by getStaticPaths.

InvalidGetStaticPathsReturn: Invalid type returned by getStaticPaths. Expected an array, got RETURN_TYPE (E03011)

getStaticPaths’s return value must be an array of objects.

pages/blog/[id].astro
export async function getStaticPaths() {
  return [ // <-- Array
    { params: { slug: "blog" } },
    { params: { slug: "about" } }
  ];
}

See Also:

getStaticPaths RSS helper is not available anymore.

Section titled getStaticPaths RSS helper is not available anymore.

GetStaticPathsRemovedRSSHelper: The RSS helper has been removed from getStaticPaths. Try the new @astrojs/rss package instead. (E03012)

getStaticPaths no longer expose an helper for generating a RSS feed. We recommend migrating to the @astrojs/rssintegration instead.

See Also:

Missing params property on getStaticPaths route.

Section titled Missing params property on getStaticPaths route.

GetStaticPathsExpectedParams: Missing or empty required params property on getStaticPaths route. (E03013)

Every route specified by getStaticPaths require a params property specifying the path parameters needed to match the route.

For instance, the following code:

pages/blog/[id].astro
---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } }
  ];
}
---

Will create the following route: site.com/blog/1.

See Also:

Invalid value for getStaticPaths route parameter.

Section titled Invalid value for getStaticPaths route parameter.

GetStaticPathsInvalidRouteParam: Invalid getStaticPaths route parameter for KEY. Expected undefined, a string or a number, received VALUE_TYPE (VALUE) (E03014)

Since params are encoded into the URL, only certain types are supported as values.

/route/[id].astro
---
export async function getStaticPaths() {
  return [
    { params: { id: '1' } } // Works
    { params: { id: 2 } } // Works
    { params: { id: false } } // Does not work
  ];
}
---

In routes using rest parameters, undefined can be used to represent a path with no parameters passed in the URL:

/route/[...id].astro
---
export async function getStaticPaths() {
  return [
    { params: { id: 1 } } // /route/1
    { params: { id: 2 } } // /route/2
    { params: { id: undefined } } // /route/
  ];
}
---

See Also:

getStaticPaths() function required for dynamic routes.

Section titled getStaticPaths() function required for dynamic routes.

GetStaticPathsRequired: getStaticPaths() function is required for dynamic routes. Make sure that you export a getStaticPaths function from your dynamic route. (E03015)

In Static Mode, all routes must be determined at build time. As such, dynamic routes must export a getStaticPaths function returning the different paths to generate.

See Also:

ReservedSlotName: Unable to create a slot named SLOT_NAME. SLOT_NAME is a reserved slot name. Please update the name of this slot. (E03016)

Certain words cannot be used for slot names due to being already used internally.

See Also:

Cannot use Server-side Rendering without an adapter.

Section titled Cannot use Server-side Rendering without an adapter.

NoAdapterInstalled: Cannot use output: 'server' without an adapter. Please install and configure the appropriate server adapter for your final deployment. (E03017)

To use server-side rendering, an adapter needs to be installed so Astro knows how to generate the proper output for your targetted deployment platform.

See Also:

No import found for component.

Section titled No import found for component.

NoMatchingImport: Could not render COMPONENT_NAME. No matching import has been found for COMPONENT_NAME. (E03018)

No import statement was found for one of the components. If there is an import statement, make sure you are using the same identifier in both the imports and the component usage.

FailedToLoadModuleSSR: Could not import IMPORT_NAME. (E04001)

Astro could not import the requested file. Oftentimes, this is caused by the import path being wrong (either because the file does not exist, or there is a typo in the path)

This message can also appear when a type is imported without specifying that it is a type import.

See Also:

InvalidGlob: Invalid glob pattern: GLOB_PATTERN. Glob patterns must start with ’./’, ‘../’ or ’/‘. (E04002)

Astro encountered an invalid glob pattern. This is often caused by the glob pattern not being a valid file path.

See Also:

Example error messages:
CSSSyntaxError: Missed semicolon
CSSSyntaxError: Unclosed string
(E05001)

Astro encountered an error while parsing your CSS, due to a syntax error. This is often caused by a missing semicolon

Failed to parse Markdown frontmatter.

Section titled Failed to parse Markdown frontmatter.

Example error messages:
can not read an implicit mapping pair; a colon is missed
unexpected end of the stream within a double quoted scalar
can not read a block mapping entry; a multiline key may not be an implicit key (E06001)

Astro encountered an error while parsing the frontmatter of your Markdown file. This is often caused by a mistake in the syntax, such as a missing colon or a missing end quote.

Specified configuration file not found.

Section titled Specified configuration file not found.

ConfigNotFound: Unable to resolve --config "CONFIG_FILE". Does the file exist? (E07001)

The specified configuration file using --config could not be found. Make sure that it exists or that the path is correct

See Also:

Legacy configuration detected.

Section titled Legacy configuration detected.

ConfigLegacyKey: Legacy configuration detected: LEGACY_CONFIG_KEY. (E07002)

Astro detected a legacy configuration option in your configuration file.

See Also: