Troubleshooting: Actions 404 Not Found

Error: 404 Not Found when calling /_actions/yourAction
Warning: Modules define actions but ‘src/actions/index.ts’ is missing.

The Problem

You have defined actions in your module’s index.module.js, but when your application tries to call them (e.g., via actions.myAction()), the browser receives a 404 Not Found error. The action exists in your code, but Astro’s server doesn’t seem to know about it.

The Architecture (The Why)

The Standard Module System and Astro Actions have a subtle disconnect in how they discover code:

1. Standard Modules are distributed. Each module (vertical slice) defines its own actions in index.module.js.
2. The Core Kernel aggregates these distributed actions into a single Virtual Module (virtual:stnd/actions). This allows code to import them easily.
3. Astro Actions, however, rely on a Physical File Convention. Astro looks specifically for src/actions/index.ts to register the API endpoints.

If src/actions/index.ts is missing, Astro never “sees” the virtual module’s actions, even though they are loaded in memory. The virtual module exists, but it’s not wired to the HTTP routing layer.

Discovery (The How)

We discovered this specificity when upgrading a project to use the new Standard Kernel. The actions were correctly defined in the module manifest:

// modules/core/index.module.js
export default {
  actions: “./models/actions.ts” // Actions defined here
}

And the kernel was correctly generating the virtual module. However, requests to /_actions/requestAuthChallenge failed.

By tracing Astro’s internal requirements, we realized that the Action Handler—the part of Astro that receives HTTP requests and routes them to functions—is only initialized if it detects the specific entry point file in the project root. It does not automatically scan virtual modules for actions.

The Solution

To fix this, we need a Bridge File. We must create src/actions/index.ts and explicitly export the aggregated actions from our virtual module. This satisfies Astro’s file requirement while maintaining our distributed module architecture.

File: src/actions/index.ts

import { actions } from “virtual:stnd/actions”;

export const server = {
  …actions
};

Once this file is created, Astro detects it, initializes the Action Handler, and routes requests to the functions provided by the Standard Kernel.

Related Concepts

• modules: How the distributed module system works.
• virtual-modules: Understanding virtual:stnd/* imports.