- This property is a static reference to the error. The shape should be similar to JavaScript's native errors (TypeError, ReferenceError): pascal-cased, no spaces, no special characters etc. (ex: `ClientAddressNotAvailable`)
- This is the only part of the error message that should not be written as a full, proper sentence complete with Capitalization and end punctuation.
@ -19,8 +19,8 @@ Title:
Message:
- Begin with **what happened** and **why**. (ex: `Could not use {feature} because Server-side Rendering is not enabled.`)
- Then, **describe the action the user should take**. (ex: `Update your Astro config with `output: 'server'` to enable Server-side Rendering.`)
- Begin with **what happened** and **why**. (ex: `Could not use {feature} because Server-side Rendering is not enabled.`)
- Then, **describe the action the user should take**. (ex: `Update your Astro config with `output: 'server'` to enable Server-side Rendering.`)
- Although this does not need to be as brief as the `title`, try to keep sentences short, clear and direct to give the reader all the necessary information quickly as possible.
- Instead of writing a longer message, consider using a `hint`.
*Toredirectonastaticwebsite,the[metarefreshattribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) can be used. Certain hosts also provide config-based redirects (ex: [Netlify redirects](https://docs.netlify.com/routing/redirects/)).
*@deprecatedsinceversion2.6
*/
StaticRedirectNotAvailable:{
exportconstStaticRedirectNotAvailable={
name:'StaticRedirectNotAvailable',
title:'`Astro.redirect` is not available in static mode.',
message:
"Redirects are only available when using `output: 'server'` or `output: 'hybrid'`. Update your Astro config if you need SSR features.",
hint:'See https://docs.astro.build/en/guides/server-side-rendering/#enabling-ssr-in-your-project for more information on how to enable SSR.',
*Togettheuser's IP address in static mode, different APIs such as [Ipify](https://www.ipify.org/) can be used in a [Client-side script](https://docs.astro.build/en/guides/client-side-scripts/) or it may be possible to get the user'sIPusingaserverlessfunctionhostedonyourhostingprovider.
*/
StaticClientAddressNotAvailable:{
exportconstStaticClientAddressNotAvailable={
name:'StaticClientAddressNotAvailable',
title:'`Astro.clientAddress` is not available in static mode.',
message:
"`Astro.clientAddress` is only available when using `output: 'server'` or `output: 'hybrid'`. Update your Astro config if you need SSR features.",
hint:'See https://docs.astro.build/en/guides/server-side-rendering/#enabling-ssr-in-your-project for more information on how to enable SSR.',
*A[dynamicroute](https://docs.astro.build/en/core-concepts/routing/#dynamic-routes) 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.
*/
NoMatchingStaticPathFound:{
exportconstNoMatchingStaticPathFound={
name:'NoMatchingStaticPathFound',
title:'No static path found for requested path.',
message:(pathName: string)=>
`A \`getStaticPaths()\` route pattern was matched, but no matching static path was found for requested path \`${pathName}\`.`,
hint:(possibleRoutes: string[])=>
`Possible dynamic routes being matched: ${possibleRoutes.join(', ')}.`,
*ForJSX/TSXfiles,[@astrojs/react](https://docs.astro.build/en/guides/integrations-guide/react/), [@astrojs/preact](https://docs.astro.build/en/guides/integrations-guide/preact/) or [@astrojs/solid-js](https://docs.astro.build/en/guides/integrations-guide/solid-js/) can be used. For Vue and Svelte files, the [@astrojs/vue](https://docs.astro.build/en/guides/integrations-guide/vue/) and [@astrojs/svelte](https://docs.astro.build/en/guides/integrations-guide/svelte/) integrations can be used respectively
*/
NoMatchingRenderer:{
exportconstNoMatchingRenderer={
name:'NoMatchingRenderer',
title:'No matching renderer found.',
message:(
componentName: string,
@ -171,7 +179,7 @@ but ${plural ? 'none were' : 'it was not'} able to server-side render \`${compon
}`,
hint:(probableRenderers: string)=>
`Did you mean to enable the ${probableRenderers} integration?\n\nSee https://docs.astro.build/en/core-concepts/framework-components/ for more information on how to install and configure integrations.`,
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -181,12 +189,13 @@ but ${plural ? 'none were' : 'it was not'} able to server-side render \`${compon
`\`${componentName}\` component has a \`client:${clientDirective}\` directive, but no client entrypoint was provided by \`${rendererName}\`.`,
hint:'See https://docs.astro.build/en/reference/integrations-reference/#addrenderer-option for more information on how to configure your renderer.',
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -199,13 +208,14 @@ but ${plural ? 'none were' : 'it was not'} able to server-side render \`${compon
*<SomeReactComponentclient:only="react"/>
*```
*/
NoClientOnlyHint:{
exportconstNoClientOnlyHint={
name:'NoClientOnlyHint',
title:'Missing hint on client:only directive.',
message:(componentName: string)=>
`Unable to render \`${componentName}\`. When using the \`client:only\` hydration strategy, Astro needs a hint to use the correct renderer.`,
hint:(probableRenderers: string)=>
`Did you mean to pass \`client:only="${probableRenderers}"\`? See https://docs.astro.build/en/reference/directives-reference/#clientonly for more information on client:only`,
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -225,12 +235,36 @@ but ${plural ? 'none were' : 'it was not'} able to server-side render \`${compon
*---
*```
*/
InvalidGetStaticPathParam:{
exportconstInvalidGetStaticPathParam={
name:'InvalidGetStaticPathParam',
title:'Invalid value returned by a `getStaticPaths` path.',
message:(paramType)=>
`Invalid params given to \`getStaticPaths\` path. Expected an \`object\`, got \`${paramType}\``,
hint:'See https://docs.astro.build/en/reference/api-reference/#getstaticpaths for more information on getStaticPaths.',
*`getStaticPaths`'sreturnvaluemustbeanarrayofobjects.Inmostcases,thiserrorhappensbecauseanarrayofarraywasreturned.Using[`.flatMap()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap) or a [`.flat()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) call may be useful.
`Invalid entry returned by getStaticPaths. Expected an object, got \`${entryType}\``,
hint:"If you're using a `.map` call, you might be looking for `.flatMap()` instead. See https://docs.astro.build/en/reference/api-reference/#getstaticpaths for more information on getStaticPaths.",
}satisfiesErrorData;
/**
*@docs
*@see
@ -248,12 +282,14 @@ but ${plural ? 'none were' : 'it was not'} able to server-side render \`${compon
*}
*```
*/
InvalidGetStaticPathsReturn:{
exportconstInvalidGetStaticPathsReturn={
name:'InvalidGetStaticPathsReturn',
title:'Invalid value returned by getStaticPaths.',
message:(returnType)=>
`Invalid type returned by \`getStaticPaths\`. Expected an \`array\`, got \`${returnType}\``,
hint:'See https://docs.astro.build/en/reference/api-reference/#getstaticpaths for more information on getStaticPaths.',
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -261,12 +297,13 @@ but ${plural ? 'none were' : 'it was not'} able to server-side render \`${compon
title:'getStaticPaths RSS helper is not available anymore.',
message:
'The RSS helper has been removed from `getStaticPaths`. Try the new @astrojs/rss package instead.',
hint:'See https://docs.astro.build/en/guides/rss/ for more information.',
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -287,11 +324,12 @@ but ${plural ? 'none were' : 'it was not'} able to server-side render \`${compon
*```
*Willcreatethefollowingroute:`site.com/blog/1`.
*/
GetStaticPathsExpectedParams:{
exportconstGetStaticPathsExpectedParams={
name:'GetStaticPathsExpectedParams',
title:'Missing params property on `getStaticPaths` route.',
message:'Missing or empty required `params` property on `getStaticPaths` route.',
hint:'See https://docs.astro.build/en/reference/api-reference/#getstaticpaths for more information on getStaticPaths.',
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -326,12 +364,13 @@ but ${plural ? 'none were' : 'it was not'} able to server-side render \`${compon
*---
*```
*/
GetStaticPathsInvalidRouteParam:{
exportconstGetStaticPathsInvalidRouteParam={
name:'GetStaticPathsInvalidRouteParam',
title:'Invalid value for `getStaticPaths` route parameter.',
message:(key: string,value: any,valueType: any)=>
`Invalid getStaticPaths route parameter for \`${key}\`. Expected undefined, a string or a number, received \`${valueType}\` (\`${value}\`)`,
hint:'See https://docs.astro.build/en/reference/api-reference/#getstaticpaths for more information on getStaticPaths.',
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -341,7 +380,8 @@ but ${plural ? 'none were' : 'it was not'} able to server-side render \`${compon
*@description
*In[StaticMode](https://docs.astro.build/en/core-concepts/routing/#static-ssg-mode), all routes must be determined at build time. As such, dynamic routes must `export` a `getStaticPaths` function returning the different paths to generate.
*/
GetStaticPathsRequired:{
exportconstGetStaticPathsRequired={
name:'GetStaticPathsRequired',
title:'`getStaticPaths()` function required for dynamic routes.',
message:
'`getStaticPaths()` function is required for dynamic routes. Make sure that you `export` a `getStaticPaths` function from your dynamic route.',
@ -349,7 +389,7 @@ but ${plural ? 'none were' : 'it was not'} able to server-side render \`${compon
Alternatively,set\`output: "server"\` in your Astro config file to switch to a non-static server build. This error can also occur if using \`export const prerender = true;\`.
Seehttps://docs.astro.build/en/guides/server-side-rendering/ for more information on non-static rendering.`,
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -357,11 +397,12 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
title:'Cannot use Server-side Rendering without an adapter.',
message:`Cannot use \`output: 'server'\` or \`output: 'hybrid'\` without an adapter. Please install and configure the appropriate server adapter for your final deployment.`,
hint:'See https://docs.astro.build/en/guides/server-side-rendering/ for more information.',
hint:"The `alt` property is important for the purpose of accessibility, without it users using screen readers or other assistive technologies won't be able to understand what your image is supposed to represent. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-alt for more information.",
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -457,11 +504,12 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
hint:'If your image is inside your `src` folder, you probably meant to import it instead. See [the Imports guide for more information](https://docs.astro.build/en/guides/imports/#other-assets).',
},
}satisfiesErrorData;
/**
*@docs
*@description
@ -498,14 +545,15 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
*<imgsrc={rocket.src}width={rocket.width}height={rocket.height}alt="A rocketship in space."/>
title:'Prerendered dynamic endpoint has path collision.',
message:(pathname: string)=>
`Could not render \`${pathname}\` with an \`undefined\` param as the generated path will collide during prerendering. Prevent passing \`undefined\` as \`params\` for the endpoint's \`getStaticPaths()\` function, or add an additional extension to the endpoint's filename.`,
hint:(filename: string)=>
`Rename \`${filename}\` to \`${filename.replace(/\.(js|ts)/,(m)=>`.json`+m)}\``,
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -542,12 +591,13 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
message:'The response has already been sent to the browser and cannot be altered.',
},
}satisfiesErrorData;
/**
*@docs
@ -612,11 +665,11 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
*});
*```
*/
MiddlewareNoDataOrNextCalled:{
exportconstMiddlewareNoDataOrNextCalled={
name:'MiddlewareNoDataOrNextCalled',
title:"The middleware didn't return a response or call `next`.",
message:
'The middleware needs to either return a `Response` object or call the `next` function.',
},
message:'The middleware needs to either return a `Response` object or call the `next` function.',
}satisfiesErrorData;
/**
*@docs
@ -631,10 +684,11 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
*});
*```
*/
MiddlewareNotAResponse:{
exportconstMiddlewareNotAResponse={
name:'MiddlewareNotAResponse',
title:'The middleware returned something that is not a `Response` object.',
message:'Any data returned from middleware must be a valid `Response` object.',
},
}satisfiesErrorData;
/**
*@docs
@ -651,12 +705,13 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
*});
*```
*/
LocalsNotAnObject:{
exportconstLocalsNotAnObject={
name:'LocalsNotAnObject',
title:'Value assigned to `locals` is not accepted.',
message:
'`locals` can only be assigned to an object. Other values like numbers, strings, etc. are not accepted.',
hint:'If you tried to remove some information from the `locals` object, try to use `delete` or set the property to `undefined`.',
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -677,11 +732,12 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
*<Imagesrc={myImage.src}alt="Cool image"/>
*```
*/
LocalImageUsedWrongly:{
exportconstLocalImageUsedWrongly={
name:'LocalImageUsedWrongly',
title:'ESM imported images must be passed as-is.',
message:(imageFilePath: string)=>
`\`Image\`'s and \`getImage\`'s \`src\` parameter must be an imported image or an URL, it cannot be a filepath. Received \`${imageFilePath}\`.`,
},
}satisfiesErrorData;
/**
*@docs
@ -690,12 +746,13 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
*@description
*`Astro.glob()`canonlybeusedin`.astro`files.Youcanuse[`import.meta.glob()`](https://vitejs.dev/guide/features.html#glob-import) instead to acheive the same result.
*/
AstroGlobUsedOutside:{
exportconstAstroGlobUsedOutside={
name:'AstroGlobUsedOutside',
title:'Astro.glob() used outside of an Astro file.',
message:(globStr: string)=>
`\`Astro.glob(${globStr})\` can only be used in \`.astro\` files. \`import.meta.glob(${globStr})\` can be used instead to achieve a similar result.`,
hint:"See Vite's documentation on `import.meta.glob` for more information: https://vitejs.dev/guide/features.html#glob-import",
},
}satisfiesErrorData;
/**
*@docs
@ -704,11 +761,12 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
`Invalid glob pattern: \`${globPattern}\`. Glob patterns must start with './', '../' or '/'.`,
hint:'See https://docs.astro.build/en/guides/imports/#glob-patterns for more information on supported glob patterns.',
},
}satisfiesErrorData;
/**
*@docs
*@description
*Astrocouldn't find the correct page to render, probably because it wasn'tcorrectlymappedforSSRusage.Thisisaninternalerror.
*/
FailedToFindPageMapSSR:{
exportconstFailedToFindPageMapSSR={
name:'FailedToFindPageMapSSR',
title:"Astro couldn't find the correct page to render",
message:
"Astro couldn't find the correct page to render, probably because it wasn't correctly mapped for SSR usage. This is an internal error. Please file an issue.",
},
}satisfiesErrorData;
/**
*@docs
*@kindheading
@ -795,9 +859,10 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
'A remark or rehype plugin attempted to inject invalid frontmatter. Ensure "astro.frontmatter" is set to a valid JSON object that is not `null` or `undefined`.',
hint:'See the frontmatter injection docs https://docs.astro.build/en/guides/markdown-content/#modifying-frontmatter-programmatically for more information.',
},
}satisfiesErrorData;
/**
*@docs
*@see
@ -858,12 +927,13 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
title:'Content Schema should not contain `slug`.',
message:(collectionName: string)=>
`A content collection schema should not contain \`slug\` since it is reserved for slug generation. Remove this from your ${collectionName} collection schema.`,
hint:'See https://docs.astro.build/en/guides/content-collections/ for more on the `slug` field.',
},
}satisfiesErrorData;
/**
*@docs
@ -1010,12 +1089,13 @@ See https://docs.astro.build/en/guides/server-side-rendering/ for more informati
`\`transform()\` functions in your content config must return valid JSON, or data types compatible with the devalue library (including Dates, Maps, and Sets).\nFull error: ${parseError}`,
hint:'See the devalue library for all supported types: https://github.com/rich-harris/devalue',
},
}satisfiesErrorData;
// Generic catch-all - Only use this in extreme cases, like if there was a cosmic ray bit flip
Emanuele Stoppa
GitHub