KV troubleshooting

Diagnose missing runtime mounts, provider routing, Cloudflare bindings, Upstash credentials, local storage, and virtual config issues.

Use this page by symptom. Each section gives the likely cause, the fix, and a quick verification step.

`KV runtime is disabled.`

Cause: Runtime config has no active KV store. This usually means kv: false was configured or the Nitro module did not install.

Fix: Remove kv: false or register the integration.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@vitehub/kv/nuxt'],
})

Verify: Call a route that imports kv and runs await kv.has('probe').

Cause: The active driver is upstash, but the runtime environment does not contain a REST URL.

Fix: Set the supported URL variable:

KV_REST_API_URL=https://example.upstash.io

Verify: Restart the runtime and call the KV route again.

Cause: The active driver is upstash, but the runtime environment does not contain a REST token.

Fix: Set the supported token variable:

KV_REST_API_TOKEN=<upstash-rest-token>

Verify: Restart the runtime and call the KV route again.

Cause: Vercel hosting was detected while the active store is fs-lite.

Fix: Use the Upstash-backed driver on Vercel:

kv: {
  driver: 'upstash',
}

Then set KV_REST_API_URL and KV_REST_API_TOKEN.

Verify: Rebuild. The warning should disappear.

Cause: The runtime is reading from a different binding or namespace than the one you populated.

Fix: Check the binding name and namespace ID:

kv: {
  driver: 'cloudflare-kv-binding',
  binding: 'KV',
  namespaceId: '<kv-namespace-id>',
}

Verify: Write a new value through the app, then read the same key back through the app.

Cause: namespaceId was not available during setup.

Fix: Pass namespaceId in config or set KV_NAMESPACE_ID:

KV_NAMESPACE_ID=<kv-namespace-id>

Verify: Inspect generated Nitro or Cloudflare config for a kv_namespaces entry with the configured binding.

Cause: The fs-lite base directory defaults to .data/kv, or another config value is active.

Fix: Set the base explicitly:

kv: {
  driver: 'fs-lite',
  base: '.cache/kv',
}

Verify: Write a test value and inspect the configured directory.

Cause: The generated config ambient types are not included.

Fix: Add the package type entry:

tsconfig.json

{
  "compilerOptions": {
    "types": ["@vitehub/kv/virtual"]
  }
}

Verify: Re-run typecheck.

Cause: The configured driver is not one of the supported values.

Fix: Use one of:

'cloudflare-kv-binding'
'upstash'
'fs-lite'

Verify: Rebuild or restart dev mode.