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

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

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

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 and match the current version.