Documentation

Hono Troubleshooting

Diagnose unavailable exports, startup failures, CORS errors, and broken AI SDK streams in Hono pattern servers.

Start with the generated server's README.md. Its routes, environment variables, and security declarations are specific to that pattern.

Hono is unavailable for a pattern

Symptom: The Hono menu item is missing or unavailable.

Hono exports are offered only for verified patterns. Continue with the Next.js export, choose another verified pattern, or wait until that pattern's standalone server closure passes verification. See Compatibility & Limitations.

Download or copy is denied

Symptoms: The request returns 401 or 403, or a locked pattern opens an upgrade prompt.

  • Sign in again and confirm the account is entitled to the pattern.
  • Retry the action from the pattern page.
  • For a paid pattern, do not reuse an old or unauthenticated export URL.

Access is checked before paid Hono source is returned.

Clipboard copy fails

Browser permissions, document focus, or user-activation rules can block the Clipboard API. Use the selectable fallback dialog, or choose Download .md and attach that file to your AI coding tool.

The server does not start

Run these checks from the extracted project:

node --version
pnpm install
pnpm typecheck
pnpm dev

Confirm:

  • Node.js is >=24
  • the install completed with the exact dependency pins from package.json
  • .env exists if the pattern requires environment variables
  • PORT is numeric and available
  • the process can bind to HOST

In a container, use HOST=0.0.0.0. On a local machine, the default HOST=127.0.0.1 is usually correct.

/healthz works but the pattern route fails

The health endpoint only proves that the Hono process is listening. Check:

  1. The method and path exactly match the generated README.
  2. The request body matches the original pattern route.
  3. Every required provider or service credential is set.
  4. Provider logs do not show quota, model, or authentication errors.
  5. The README's authentication declaration is satisfied.

The browser reports a CORS error

Set the frontend's exact origin in CORS_ORIGINS:

CORS_ORIGINS=http://localhost:3000,https://app.example.com

Then restart the Hono process. Common mistakes include adding a path, using the wrong scheme or port, or forgetting a preview deployment origin.

For cookies or credentialed requests, also set:

CORS_ALLOW_CREDENTIALS=true

and configure the client to include credentials. Only enable this with explicit, trusted origins and an appropriate authentication and CSRF design.

The request succeeds but streaming is broken

Symptoms: The response arrives all at once, stops early, or works locally but not after deployment.

  • Point DefaultChatTransport at the exact Hono route, not /healthz.
  • Confirm no frontend rewrite is sending the request back to the old Next.js route.
  • Disable buffering or response transformation in the reverse proxy.
  • Increase host and proxy timeouts for long model responses.
  • Preserve the response headers used by AI SDK streams.
  • Test a direct request to Hono to isolate the frontend and proxy layers.

Next.js maxDuration does not configure the Hono process.

The frontend receives a network error

  • Confirm the Hono origin is reachable from the browser, not only from the server.
  • Do not use 127.0.0.1 in a deployed browser configuration.
  • Verify HTTPS pages call an HTTPS API origin to avoid mixed-content blocking.
  • Check that the deployment exposes the configured PORT.
  • Call /healthz from the same network path as the frontend.

AI behavior differs from the preview

The preview and exported service can use different credentials, models, service accounts, rate limits, and middleware. Compare environment values and provider configuration first. Also remember that preview wrapper authentication and rate limiting are not automatically exported.

If the server now runs correctly, continue with the production checklist.