diff --git a/.env.example b/.env.example
index c741ba39c6..734402a092 100644
--- a/.env.example
+++ b/.env.example
@@ -174,6 +174,12 @@ OMNIROUTE_USE_TURBOPACK=1
 # hints in production logs.
 # OMNIROUTE_PROXY_FETCH_DEBUG=true
 
+# Set to any non-empty value to emit `[omniroute completion]` diagnostics from
+# the CLI shell-completion cache paths (read/refresh/write) in
+# bin/cli/commands/completion.mjs. Off by default — these caches fail silently
+# so a missing/corrupt cache never breaks tab-completion.
+# OMNIROUTE_DEBUG_COMPLETION=1
+
 # Docker production port mappings (docker-compose.prod.yml only).
 # These set the HOST-side published ports. Container ports use PORT/API_PORT.
 # PROD_DASHBOARD_PORT=20130
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7999e4591a..2a17d443b7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -35,6 +35,7 @@ _Living section — bullets land here as PRs merge into `release/v3.8.47` (paral
 
 ### 📝 Maintenance
 
+- **chore(cli):** the shell-completion cache paths (`readCache`/`refreshCache`/`writeCache`) in `bin/cli/commands/completion.mjs` no longer swallow errors into a bare `catch {}` ([#6257](https://github.com/diegosouzapw/OmniRoute/pull/6257)) — each now binds the error and, when the new `OMNIROUTE_DEBUG_COMPLETION` env var is set, emits a `[omniroute completion]` diagnostic to `stderr`; the caches still fail silently by default so a missing/corrupt cache never breaks tab-completion. (thanks @KooshaPari)
 - **chore(quality):** `validate-release-green --full-ci` reproduces the full `ci.yml` static gate set locally — the pre-flight now reads `ci.yml` itself and runs every `npm run check:*` from the `lint` / `quality-gate` / `quality-extended` / `docs-sync-strict` / `pr-test-policy` jobs (`--` ratchet flags preserved, `test-masking` against `GITHUB_BASE_REF=main`), skipping only the non-local `pr-evidence`/`codeql-ratchet`. Closes the gap where 11 static base-reds leaked to the v3.8.46 release PR in ~2h of layered CI. Also wired into `nightly-release-green` so a static base-red opens a tracking issue the night it lands. Regression guard: `tests/unit/validate-release-green.test.ts` (+5 `extractCiGates` cases).
 
 ---
diff --git a/bin/cli/commands/completion.mjs b/bin/cli/commands/completion.mjs
index d1d02d944c..3fbbfe9258 100644
--- a/bin/cli/commands/completion.mjs
+++ b/bin/cli/commands/completion.mjs
@@ -15,7 +15,11 @@ function readCache() {
   try {
     const raw = JSON.parse(readFileSync(cachePath(), "utf8"));
     if (raw && typeof raw.ts === "number" && Date.now() - raw.ts < CACHE_TTL_MS) return raw;
-  } catch {}
+  } catch (err) {
+    if (process.env.OMNIROUTE_DEBUG_COMPLETION) {
+      console.error("[omniroute completion] readCache failed:", err?.message ?? err);
+    }
+  }
   return null;
 }
 
@@ -41,12 +45,20 @@ async function refreshCache(opts = {}) {
       const j = await mr.value.json();
       models = (Array.isArray(j) ? j : j.data || []).map((m) => m.id).filter(Boolean);
     }
-  } catch {}
+  } catch (err) {
+    if (process.env.OMNIROUTE_DEBUG_COMPLETION) {
+      console.error("[omniroute completion] refreshCache failed:", err?.message ?? err);
+    }
+  }
   const data = { combos, providers, models, ts: Date.now() };
   try {
     mkdirSync(dirname(cachePath()), { recursive: true });
     writeFileSync(cachePath(), JSON.stringify(data));
-  } catch {}
+  } catch (err) {
+    if (process.env.OMNIROUTE_DEBUG_COMPLETION) {
+      console.error("[omniroute completion] writeCache failed:", err?.message ?? err);
+    }
+  }
   return data;
 }
 
diff --git a/docs/reference/ENVIRONMENT.md b/docs/reference/ENVIRONMENT.md
index 1ca37d603f..1a987faff9 100644
--- a/docs/reference/ENVIRONMENT.md
+++ b/docs/reference/ENVIRONMENT.md
@@ -96,6 +96,7 @@ OmniRoute uses **SQLite** (via `better-sqlite3`) for all persistence. These vari
 | `OMNIROUTE_SPEND_FLUSH_INTERVAL_MS`    | _(default in code)_  | `src/lib/spend/batchWriter.ts`                        | Flush interval (ms) for the batched spend/cost writer. Lower values reduce write coalescing; higher values reduce DB contention.                                                                                                                |
 | `OMNIROUTE_SPEND_MAX_BUFFER_SIZE`      | _(default in code)_  | `src/lib/spend/batchWriter.ts`                        | Max buffered spend entries before a forced flush. Raise on high-QPS deployments; lower when bounded memory matters more.                                                                                                                        |
 | `OMNIROUTE_PROXY_FETCH_DEBUG`          | _(unset)_            | `open-sse/utils/proxyFetch.ts`                        | Set to `"true"` to emit `[ProxyFetch]` debug logs on the Vercel relay path. Off by default to avoid leaking routing hints.                                                                                                                      |
+| `OMNIROUTE_DEBUG_COMPLETION`           | _(unset)_            | `bin/cli/commands/completion.mjs`                    | Set to any non-empty value to emit `[omniroute completion]` diagnostics from the CLI shell-completion cache paths (read/refresh/write). Off by default — those caches fail silently so a missing/corrupt cache never breaks tab-completion.       |
 | `BATCH_RETRY_DURATION_MS`              | `86400000` (24h)     | `open-sse/services/batchProcessor.ts`                 | Maximum retry window for individual batch items (ms). Items exceeding this duration are marked failed.                                                                                                                                          |
 | `BATCH_BACKOFF_BASE_MS`                | `5000`               | `open-sse/services/batchProcessor.ts`                 | Base delay (ms) for exponential backoff on batch item retries.                                                                                                                                                                                  |
 | `BATCH_BACKOFF_MAX_MS`                 | `3600000` (1h)       | `open-sse/services/batchProcessor.ts`                 | Cap (ms) for exponential backoff between batch item retries.                                                                                                                                                                                    |