Common Issues

This guide covers common issues you might encounter while working on the FiNAN documentation or website.

Build Failures

Missing Assets

If the build fails with an error like Module not found: Error: Can't resolve './image.png', it usually means an image path is incorrect.

Solution:

1. Verify the file exists in src/assets/.
2. Check for typos in the filename.
3. Ensure you are using a relative path (e.g., ../../assets/image.png) or alias if configured.

Invalid Frontmatter

All .mdx files in src/content/docs must have valid YAML frontmatter.

Error:

[Astro] content-docs: Invalid frontmatter. "title" is required.

Solution: Ensure every file starts with:

---
title: Page Title
description: Brief description
---

Image Errors

Local vs. Public Folder

Tip

Always prefer src/assets/ for images component usage. Use public/ only for static assets like robots.txt or favicon.ico that need a stable URL.

Issue: Image not loading or 404 error.

Solution:

• If the image is in src/assets/, import it in your component or use the relative markdown syntax ![Alt](./path-to-image.png).
• If the image is in public/, reference it with a leading slash /image.png.

Ghost CMS Issues

API Key Errors

Issue: “Failed to fetch posts” or “Unauthorized”.

Solution:

1. Check your .env file.
2. Ensure CONTENT_API_KEY and API_URL are set correctly.
3. Restart the dev server (pnpm dev) after changing .env files.

Missing Content

Issue: A new post isn’t showing up.

Solution:

1. Verify the post is Published (not Draft) in Ghost Admin.
2. Check if the post has the correct Tag (e.g., #finland for the Finland page).
3. The build is static; you must rebuild the site to fetch new content.

TypeScript Errors

”Property ‘X’ does not exist on type ‘Y’”

This is common when working with data objects.

Solution:

1. Check the relevant type definition in src/data/.
2. Ensure your data matches the schema.
3. If you added a new property, update the TypeScript interface.

// Example: Updating a type
export interface CommitteeMember {
  name: string;
  role: string;
  image: ImageMetadata;
  // Add new optional property
  linkedinUrl?: string;
}