Troubleshooting

Start with the page that owns the failure:

1. Install or package resolution: Compatibility And Publication and Install.
2. Copied files and Actions: Astro Storefront and Astro Actions.
3. Backend, provider, and webhook failures: Backend And Provider, Provider Contract, and Stripe And Webhook Cookbook.
4. Route boundary confusion: Route Surfaces and Plugin Routes.

Install Fails With npm E404

Cause: the package may not be published yet, or the host is using a registry install before release.

@bnomei/emdash-mika may not be published yet. In this workspace, use the sibling package:

{
  "dependencies": {
    "@bnomei/emdash-mika": "file:../emdash-mika"
  }
}

Then build the package before running the host app. The seeded template does this with lifecycle scripts.

EmDash Version Is Too New

Cause: the resolved EmDash version is outside Mika’s peer range.

Check ../emdash-mika/package.json. The current Mika source peers emdash >=0.22.0 <1.0.0. If npm install emdash resolves outside that range, pin EmDash to the supported range until Mika’s peer range changes.

actions.mika.* Is Undefined

Cause: the host has copied forms before registering the server.mika action tree.

Confirm:

• src/actions/mika.ts re-exports createMikaActions;
• src/actions/index.ts exports server = { mika: createMikaActions() };
• the copied form imports actions from astro:actions;
• the action name exists in the operation tree, for example actions.mika.cart.add or actions.mika.checkout.start;
• the app is running on Astro with Actions enabled.

Astro ActionError Code Looks Wrong

Mika converts failed API result envelopes into Astro ActionError codes. When a form returns one of these codes, debug the Mika status and host policy that produced it:

ActionError code	Usual Mika status	First place to check
UNAUTHORIZED	401	Missing account/customer context, magic-link/session wiring, or auth guard.
FORBIDDEN	403	Host guard or operationPolicy denied the operation.
CONFLICT	409	Idempotency replay mismatch, stock conflict, terminal session state, or required idempotency key.
UNPROCESSABLE_CONTENT	422	Valid Action shape but invalid commerce input, quote, checkout, fulfillment, or account state.
TOO_MANY_REQUESTS	429	Host rate limit or policy throttle.
SERVICE_UNAVAILABLE	503	Provider, repository, or maintenance dependency is temporarily unavailable.
BAD_REQUEST	Other status	Input or route mismatch that did not map to a more specific code.

The exact mapping is listed in Astro Actions.

NOT_IMPLEMENTED

Mika’s test/partial API mode returns 501 NOT_IMPLEMENTED for unwired methods. Either implement the missing MikaApiOverrides method for fixtures or switch to createMikaBackendApi() with the required repositories/providers.

Use assertMikaApiWired(api, { scope }) in setup tests when a route must fail early if a backend method is still a stub.

AUTH_REQUIRED

AUTH_REQUIRED means the operation needs a signed-in or resolved customer context. Account pages should treat it as a sign-in state, not as a generic crash.

Magic-link request/verify actions are provided, but the host owns session policy, delivery, stronger auth, and account gating.

Checkout Redirect Does Nothing

On the page that receives the form POST, call Astro.getActionResult(actions.mika.checkout.start) before rendering the cart/product view. If checkout.data.redirectUrl exists, redirect to it.

Also confirm a provider is configured and advertises hosted checkout capability.

Webhook Signature Fails

Cause: the provider adapter cannot verify the original raw request body or expected signature headers.

Confirm:

• the endpoint passes the original Request to createMika({ request, url }, { includeWebhook: true });
• no middleware has consumed and reserialized the request body before Mika reads it;
• the provider route param matches the registered provider id;
• Stripe requests include Stripe-Signature;
• the host set STRIPE_WEBHOOK_SECRET for the adapter.

Public Route Missing

The browser-safe plugin JSON routes are only:

• /_emdash/api/plugins/mika/catalog/sellables;
• /_emdash/api/plugins/mika/sellables/availability.

Cart, checkout, account, subscription, webhook, admin, and agent-tool mutations are not public plugin JSON routes. Use Astro Actions or host-owned protected endpoints.

Build Or Prerender Fails On Copied Pages

Copied cart, wishlist, checkout, account, download, and webhook files are request-bound. Use output: "server" or mark those pages/endpoints with export const prerender = false.

Cloudflare Variant Overwrote Files

The variant commands copy package.cf.json, astro.config.cf.mjs, wrangler.cf.jsonc, and worker.cf.ts over real host filenames. Restore from git, then retry on a branch and replace placeholder D1/R2 binding values before deploy.

Source Anchors

• ⓟ ../emdash-mika/package.json
• ⓟ ../emdash-mika/src/api/server.ts
• ⓟ ../emdash-mika/src/api/operations.ts
• ⓟ ../emdash-mika/src/astro-actions.ts
• ⓟ ../emdash-mika/src/provider.ts
• ⓟ ../emdash-mika/src/stripe.ts
• ⓐ ../emdash-mika/src/templates/astro/pages/api/mika-webhook/[provider].ts
• ⓣ ../emdash-mika-template/package.json