Troubleshooting

A page returns 404

Confirm that the file belongs to the collection and that the application has a matching Nuxt page route.

1. The file matches the collection source.
2. The collection uses type: 'page'.
3. The collection route matches the Nuxt page route.
4. The page imports the intended collection handle.
5. The document is not a partial or a production draft.
6. The requested locale exists or the intended fallback is enabled.

useContentPage() does not throw a 404 itself. In a catch-all page, key setup by route.path, check page.value after the awaited read, and throw a fatal Nuxt createError({ statusCode: 404, fatal: true }). This applies the same route-owned policy to direct requests and client navigation; see the composable recipe.

A link uses the wrong URL

Use document.route.resolvedPath for document links. Navigation and search results expose their link as path.

Inspect route.requestedPath, route.resolvedPath, and route.alternates before adding redirects. Never render canonicalKey, file, or a provider identifier as a URL.

Navigation is empty

Check the collection handle, locale, source glob, and visibility fields. Navigation always omits partials and documents with navigation: false; production also omits drafts. With an external provider, confirm that it implements navigation for the requested collection and locale.

Search works in development but not production

Test the production preview over HTTP, then check the deployed search assets and active locale.

• Confirm MiniSearch or Pagefind assets were included in the deployment.
• Keep useContentSearch() outside <ClientOnly> when generated pages need its payload.
• Confirm Pagefind ran against the generated HTML.
• Confirm the active locale contains indexed documents.
• For provider search, test the runtime endpoint and its credentials.

Locale fallback is unexpected

Make Nuxt I18n and Ginko use the same locale codes and default locale. Inspect resolution.requested, resolution.resolved, and resolution.usedFallback. List queries remain locale-scoped unless the operation explicitly requests other behavior.

Validation fails

Read the collection, source file, field path, and Zod issue together. Fix the authored value or the schema; a page component should not normalize invalid source data after ingestion.

A provider rejects a query

Compare the requested operators and pagination mode with provider.capabilities. Narrow the query or implement and test the missing capability. Ginko does not silently emulate unsupported provider behavior.

Agent Markdown is missing

Confirm that content.agent routes are enabled, content.config.ts declares an agent site, and the collection enables agent Markdown. Static deployments must include the generated raw and LLM routes.

Reporting a problem

Include:

• Ginko, Nuxt, Node.js, and package-manager versions;
• provider and deployment target;
• a minimal collection and module configuration;
• the exact route or query;
• development and production behavior;
• the smallest content tree that reproduces the problem;
• complete error output.