Troubleshooting

Guidelines and tips for troubleshooting common issues in Astro projects.
astro
          
            ## Astro Troubleshooting Guidelines

1.  Debugging with `console.log()`:

    - Logs in the component script (`---` fences) appear in the server terminal.
    - Logs in `<script>` tags (client-side JavaScript) appear in the browser console.
    - Framework components log to the terminal during SSR/build and potentially the browser after hydration (`client:*`).

2.  Debugging with `<Debug />`:

    - Import `{ Debug } from 'astro:components';`
    - Use `<Debug {...Astro.props} {variable1} {variable2} />` in your template to inspect prop/variable values directly in the browser output (during development).

3.  Common Error Messages:

    - `Cannot use import statement outside a module`: Usually means trying to use `import` in a non-module script. Ensure client-side `<script>` tags intended for bundling don't have attributes like `is:inline` that prevent processing, or ensure inline scripts don't use `import`.
    - `document`/`window` is not defined: Accessing browser-specific globals (like `document` or `window`) in server-side code (component script `---`). Wrap such code in client-side `<script>` tags or check `import.meta.env.SSR` conditionally.
    - `Expected a default export`: Typically when importing a component or layout. Ensure the imported file has a `export default ...` statement if required by how you're importing it.
    - `Refused to execute inline script`: Related to Content Security Policy (CSP). Check deployment environment CSP settings if using inline scripts (`is:inline`).

4.  Common Gotchas:

    - Component Not Rendering:
      - Verify the import path is correct.
      - Ensure the component file has the correct extension (`.astro`, `.jsx`, etc.).
      - Check if the component has a default export if needed.
    - Component Not Interactive (UI Frameworks):
      - Missing a `client:*` directive (e.g., `client:load`, `client:visible`). Components render as static HTML by default without hydration.
      - Astro components (`.astro`) are HTML-only templates; use `<script>` tags for client-side interactivity.
    - Cannot find package 'X':
      - Integrations (e.g., `@astrojs/react`) often require installing the underlying framework (`react`, `react-dom`) as a peer dependency. Install them explicitly.
    - Yarn 2+ (Berry) Issues: Set `nodeLinker: "node-modules"` in `.yarnrc.yml` if encountering PnP-related problems.
    - Monorepo Issues: Add Astro-related dependencies used in the root to `vite.ssr.noExternal` in `astro.config.mjs`.
    - Using `<head>` in Components: Avoid placing `<head>` tags directly in regular components. Use a single `<head>` within a layout component for the entire page.
    - Unexpected `<style>` Included: Astro bundles CSS for all imported components in the module graph, even if a component isn't conditionally rendered in the final HTML.

5.  Escaping Special Characters in Markdown: Use HTML entities (e.g., `&lt;` for `<`, `&gt;` for `>`) to display characters that have special meaning in Markdown/HTML.

6.  Creating Minimal Reproductions:

    - When asking for help or reporting bugs, create a small, isolated project demonstrating the issue.
    - Use `astro.new` (StackBlitz) or create a minimal local project and push to GitHub.
    - Include only the code necessary to reproduce the problem.

7.  Getting Help:
    - Astro Discord (`#support` channel).
    - GitHub Issues (check existing issues first, include minimal reproduction).
    - RFC Discussions for potential limitations or feature proposals.

Reference: [Astro Troubleshooting Docs](https://docs.astro.build/en/guides/troubleshooting/)