Deno "Could not find ... in cache" with --cached-only in CI

With --cached-only (or a frozen offline run), Deno refuses to reach the network and can only use already-cached modules. A module that was never cached, or a DENO_DIR that CI did not restore, causes this failure.

What this error means

The run fails with "error: Specifier not found in cache, ... --cached-only is specified." naming a module that is not in DENO_DIR.

deno

error: Specifier not found in cache: "https://jsr.io/@std/assert/1.0.0/mod.ts", --cached-only is specified.
    at file:///home/runner/work/app/app/src/main.ts:1:24

Common causes

The DENO_DIR cache was not restored in CI

A previous step or job cached modules, but this job did not restore DENO_DIR, so nothing is present for the offline run.

A dependency was added without pre-caching

A new import was never fetched into the cache, so --cached-only cannot find it.

How to fix it

Pre-cache dependencies before the offline run

Run deno cache (online) to populate DENO_DIR first.
Then run the program or tests with --cached-only.
Cache DENO_DIR between jobs so it is restored.

Terminal

deno cache main.ts
deno run --cached-only main.ts

Restore DENO_DIR with actions/cache

Persist and restore the Deno cache directory keyed on the lockfile so cached modules are present.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.cache/deno
    key: deno-${{ hashFiles('deno.lock') }}

How to prevent it

Run deno cache to populate DENO_DIR before any --cached-only step.
Cache and restore DENO_DIR keyed on deno.lock.
Add new imports to the cache before enforcing offline runs.