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 ^1.2.0. If the host resolves an older 0.x release or an unsupported newer major, update its dependency to the supported range. Do not force installation through a peer conflict; align Astro and Node with Compatibility And Publication too.

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({ api }) };
• 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.

Action Appears Successful Despite A Commerce Failure

Cause: old code assumes a truthy Action data is a DTO, or expects commerce failures to become Astro ActionError values.

In the unpublished 0.2.0 target, ordinary actions.mika.* preserve Mika’s result inside Astro’s safe result:

Branch	Meaning	First place to check
result.error	Astro validation/input-normalization or host guard failure	Action input fields and host guard.
result.data.ok === false	Commerce failure	result.data.status and stable result.data.error.code; backend, provider, operation policy, or account context.
result.data.ok === true	Mika success	Read the DTO at result.data.data.

There is no HTTP-status-to-ActionError mapping for commerce failures. .orThrow() still returns Mika’s envelope and does not turn ok: false into an exception. Branch on codes, not message text. Direct createMika() server helpers remain single-layer result.ok / result.data results.

See Astro Actions. The separate storefront tool surface has a different response contract; see Browser Shopping Tools and Storefront Tools.

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. Only if checkout?.data?.ok && checkout.data.data.redirectUrl, redirect to checkout.data.data.redirectUrl. Show Astro failures from checkout.error and commerce failures from checkout.data.error when checkout.data.ok === false.

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