Debugging and Troubleshooting

next-nexus includes a verbose logging system to help you understand its behavior during development.

Enabling Debug Logs

To enable detailed logs, add the following variable to your .env.local file:

NEXT_PUBLIC_NEXUS_DEBUG=true

With this flag, next-nexus will print information about requests, cache interactions, and hydration to your browser’s developer console.

Understanding Log Events

Request Events

• START: A request has started.
• SUCCESS: A request finished successfully.
• ERROR: A request failed.
• TIMEOUT: A request was aborted due to a timeout.

Cache Events

• HIT: A fresh entry was found in the client cache.
• HIT-STALE: A stale entry was found in the client cache.
• MISS: No entry was found in the client cache.
• SET: An item was added to the cache.
• UPDATE: An existing item in the cache was updated.
• DELETE: An item was removed from the cache.

Hydration & Delegation Events

• HYDRATE: The client cache was hydrated with server-rendered data.
• DELEGATE: NexusRenderer delegated rendering to the client because of a fresh cache entry.
• SKIP: The server skipped hydrating a key because the client already has the same version (ETag match).
• MATCH: The server found a matching entry in the client’s cache metadata.

Common Troubleshooting Scenarios

Hydration is not working

• Check for the boundary: Ensure the page or layout is wrapped with NexusHydrationBoundary or withNexusHydrationBoundary.
• Check for NexusRuntime: Verify that <NexusRuntime /> is present in your root layout.
• Check the definition: The exact same definition object (including method, endpoint, tags, etc.) must be used on both the server (for nexus) and the client (for useNexusQuery). Any discrepancy will result in a cache key mismatch.

Cached headers are missing

• Check cachedHeaders: Confirm that the header name you are trying to read on the client is included in the client.cachedHeaders array in the definition.