# Common errors and troubleshooting

## Classify the failure

| Symptom | Inspect first | Do not immediately |
| --- | --- | --- |
| `NotCapable` / requires access | resource and permission in the error | add `-A` |
| Module not found | specifier, imports, workspace, effective config | delete lockfile |
| npm package misses a file | node_modules mode, exports, install scripts | patch package internals |
| Type errors but execution works | `deno check` graph and type sources | ignore CI |
| CI works, local fails | Deno version, OS/arch, cache, environment | wipe all global caches |
| Local works, deploy fails | request runtime, permissions, read-only FS, variables | assume platform equals laptop |

## Permission failure

```text
error: Requires env access to "API_KEY"
```

Confirm that the code needs the variable, then use `--allow-env=API_KEY`. If a user controls the variable name, avoid granting the entire environment.

## Module failure

```bash
deno info main.ts
deno install --reload --entrypoint main.ts
```

`deno cache` is deprecated in the current CLI; use `deno install --entrypoint`. `--reload` accesses the network and changes local cache state, so use it only after deciding resolution should be refreshed. Never delete `deno.lock` automatically because CI failed.

## Reproducible report

```text
Deno: <deno --version output>
Platform: <os/arch>
Command: <exact command, secrets removed>
Expected: <observable behavior>
Actual: <exit code + first relevant error>
Config: <effective deno.json path>
Minimal reproduction: <path or repository>
```

When testing for a runtime bug, search [denoland/deno issues](https://github.com/denoland/deno/issues) and match the current version.