a0deploy windows path error import cannot find files bug

Not specified by the original author.

TL;DR

Wrangler cannot find your entry file, so the deploy stops before it uploads anything. Nine times out of ten the main path in wrangler.toml points at a file that moved or was renamed, or you ran deploy from the wrong directory. Check that the file exists relative to the config, fix the path or cd into the worker package, then redeploy.

Error: could not find worker script

Steps

1. Confirm you are in the worker's directory and the config is here:

pwd
ls wrangler.toml wrangler.jsonc

Expected: pwd shows the worker package directory, and one of the two config files is listed.

2. Read the main value from the config, then check that exact file exists:

grep -n '^main' wrangler.toml
test -f src/index.ts && echo entry found

Expected: the grep shows a path like main = "src/index.ts", and the test prints "entry found". If it does not, the path is wrong or the file moved.

3. Fix the mismatch. Either update main to the real relative path, or run the deploy from the directory that holds the config. In a monorepo, pass the config explicitly:

wrangler deploy --config packages/api/wrangler.toml

Expected: wrangler finds the entry and starts bundling instead of erroring.

4. Run the full deploy and watch for the upload summary:

wrangler deploy

Expected: a "Total Upload" line and a deployed workers.dev URL, no script error.

Use this when

• wrangler deploy fails with "could not find worker script"
• The error appeared right after renaming or moving the entry file
• Deploying a monorepo package from the repo root
• The config references an entry path that does not exist on disk

Not for this skill when

• The deploy fails on script size (see the script-too-large skill)
• The entry file exists but the deploy fails on bindings or config validation
• The error is at runtime in the browser, not at deploy time
• You are deploying Pages, not a Worker

Variant phrasings

• wrangler deploy could not find worker script
• "could not find worker script" wrangler
• wrangler error finding worker entry point on deploy

Why it happens

Wrangler resolves the main entry path relative to the config file, not relative to your shell's working directory. The default scaffold expects src/index.ts (older templates used src/index.js), so any rename, move, or deploy run from a parent directory breaks the lookup. Monorepo CI jobs that run from the repo root hit this constantly.

Edge cases

• If both wrangler.toml and wrangler.jsonc exist, wrangler prefers one of them; make sure you are editing the file it actually reads.
• A main path that exists but points at a directory instead of a file fails the same way.
• Case-sensitive filesystems: Src/index.ts is not src/index.ts on Linux CI even if it works on macOS.
• After fixing, a stale wrangler dev process may still serve the old bundle; restart it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_GHaDGsZdiBGvp16OMpUJFA

Resolved from the public thread: https://vectle.com/posts/pst_GHaDGsZdiBGvp16OMpUJFA

Thread query: "Error: could not find worker script" on wrangler deploy

TL;DR: Wrangler cannot find your entry file, so the deploy stops before it uploads anything. Nine times out of ten the main path in wrangler.toml points at a file that moved or was renamed, or you ran deploy from the wrong directory. Check that the file exists relative to the config, fix the path or cd into the worker package, then redeploy.

Not specified by the original author.

TL;DR

az is not recognized as an internal or external command means Windows cannot find the Azure CLI executable: the CLI installed but its folder is not on PATH, or the install did not finish. Reinstall from the official MSI with the add to PATH option checked, or add the install folder to PATH manually, then open a fresh terminal and verify with az version. A terminal opened before the fix will never see the new PATH.

'az' is not recognized as an internal or external command,
operable program or batch file.

Use this when

• cmd prints az is not recognized as an internal or external command, operable program or batch file
• PowerShell prints the term az is not recognized as the name of a cmdlet
• This happens right after installing the Azure CLI on Windows, or in a terminal that was open during the install

Not for this skill when

• az runs but az login fails. The CLI is found there; authentication is the problem, see the related application id skill below
• You are inside Azure Cloud Shell. Cloud Shell always has the CLI; a not recognized message there is a different issue

Steps

1. Check whether the CLI is actually installed. Look for Azure CLI in Add or remove programs, and for its folder under Program Files.

Expected: you know whether this is a missing install (go to step 3) or a PATH problem (go to step 2).

2. If it is installed, add its folder to PATH. Add the Azure CLI bin folder to the system PATH in Environment Variables, then close the terminal completely and open a new one.

Expected: az version prints version info in the fresh terminal.

3. If it is not installed, or the folder is missing, reinstall from the official MSI and keep the add to PATH option checked.

Expected: the installer completes, and a fresh terminal finds az.

4. In PowerShell, confirm the shell resolves it: Get-Command az.

Expected: it resolves to the CLI executable path instead of an error.

5. Verify the install end to end: az version.

Expected: JSON output with the Azure CLI version. Only now try az login or your original command.

Variant phrasings

az not recognized windows

The short version of the same report. It is the PATH problem in step 2 nine times out of ten; do the fresh-terminal check before reinstalling.

the term az is not recognized as the name of a cmdlet

The PowerShell wording of the identical failure. PowerShell and cmd read the same PATH, so the fix is the same: folder on PATH, fresh terminal, Get-Command az to confirm.

az login not recognized

az login never gets to run because the shell cannot find az at all. Fix PATH first (steps 1 to 5); login errors only become visible after az version works.

Root cause

The MSI installer optionally adds the CLI folder to PATH. Unchecking that option, an install that did not finish, or a terminal opened before the install leaves az unresolvable. The step everyone skips is opening a fresh terminal: already-open shells keep the old PATH forever.

Edge cases

• 32-bit and 64-bit installs land in different Program Files folders. Point PATH at the one that actually exists on disk.
• Corporate images sometimes block the MSI PATH change. Set PATH manually in System environment variables instead.
• Multiple Python-based CLI installs can shadow each other. Get-Command az shows which executable the shell actually resolved.

Tool compatibility

Azure CLI on Windows (MSI install), in cmd and PowerShell. The PATH principle is the same for winget installs; the folder location differs.

Related skills

• Please run az login to setup account - the next failure after az is found but not signed in: https://vectle.com/skills/skl_7aKi9fDg6cP5dqjxQPgTHA
• application id not found (AADSTS700016), which az login can hit once the CLI runs: https://vectle.com/skills/skl_A8TLFys-hrvLfD1hrxFnDg
• azure identity not found: https://vectle.com/skills/skl_O0wm7fdvw17HY02tjklDMw

Provenance

Built from the hatchjs.com Q and A on this exact error, linked in the evidence.

The hatchjs.com Q&A ("az is not recognized as an internal or external command") and the kthw-powershell execution troubleshooting notes document this exact failure: after installing the Azure CLI on Windows, the shell cannot find az because the install folder is not on PATH. The confirmed fix is reinstalling with PATH registration or adding the install folder to PATH manually, then opening a fresh terminal session so the new PATH takes effect.

Not specified by the original author.

TL;DR

Jinja cant find your template file because the directory it lives in isnt on Airflow's template search path. The fix is to set template_searchpath on the DAG to the folder holding your templates, anchored to the DAG file's own directory so it works in every environment. This happens because Jinja only looks in its configured search paths, and the DAG file's folder is not automatically one of them.

jinja2.exceptions.TemplateNotFound: my_query.sql

Use this when

• A task fails at render time with TemplateNotFound naming a file you know exists
• The template works on your laptop but not on the scheduler or workers
• You recently moved templates into a subfolder like templates/

Not for this skill when

• Jinja finds the file but chokes on its syntax (thats a template bug, not a path bug)
• The DAG file itself is missing or failing to import
• The error is a connection or permission problem, not a missing template

Steps

1. Reproduce the failure with the exact task and logical date:

airflow tasks test my_dag my_task 2026-10-01

Expected output: the task fails during rendering with jinja2.exceptions.TemplateNotFound naming your file, confirming this is a path problem and not a query problem.

2. Inspect which search paths the task is actually using:

from airflow.models import DagBag
bag = DagBag(dag_folder="[dag folder]", include_examples=False)
task = bag.get_dag("my_dag").get_task("my_task")
print(task.template_searchpath)

Expected output: a list of directories Jinja searches. Your templates folder is probably not in it, which is the whole bug.

3. Anchor the search path to the DAG file's directory:

from pathlib import Path

TEMPLATE_DIR = str(Path(__file__).resolve().parent / "templates")

with DAG(
    dag_id="my_dag",
    template_searchpath=[TEMPLATE_DIR],
) as dag:
    ...

Expected output: template_searchpath now points at the real templates folder in every environment, because it is derived from the DAG file location instead of a hardcoded path.

4. Reference templates by filename (or subfolder-relative path) in your operators:

MyOperator(
    task_id="my_task",
    sql="my_query.sql",
)

Expected output: the operator finds templates/my_query.sql at render time. If the file sits in a subfolder, use a relative path like staging/my_query.sql.

5. Re-run the task test from step 1.

airflow tasks test my_dag my_task 2026-10-01

Expected output: the task renders the template and proceeds to execute, with no TemplateNotFound in the logs.

6. If you deploy with containers or a remote executor, verify the templates exist where the worker runs, not just on your laptop:

ls [templates dir]/my_query.sql

Expected output: the listing shows your template file. A correct path pointing at files that were never shipped is the same error with a different fix: ship the files.

Variant phrasings

jinja2.exceptions.TemplateNotFound

The full exception path you see in task logs. Everything above applies; the class name just tells you Jinja raised it rather than Airflow itself.

TemplateNotFound for a template in a subfolder

Reference it relative to the search path root, like staging/my_query.sql, and make sure the search path points at the folder containing staging/, not at staging/ itself. Pointing one level too deep is a common variant of this bug.

template not found only in production

Classic environment skew: the search path was built from a local absolute path, or the templates folder is not mounted in the deployed environment. Anchoring to the DAG file (step 3) plus verifying the files ship (step 6) covers both causes.

Why it happens

Jinja's FileSystemLoader resolves template names against a fixed list of search directories, and Airflow builds that list from the DAG's template_searchpath. The DAG file's own directory is not added automatically, so a template sitting next to the DAG is invisible unless you say so. Local absolute paths make it worse: they work on your machine and nowhere else, which is why this error loves to appear only in production.

Edge cases

• Case sensitivity: My_Query.sql and my_query.sql are different files on Linux. Match the filename exactly, including case.
• Templates referenced with an absolute path bypass the search path entirely; they work until the environment changes, then break the same way.
• Multiple DAGs sharing one templates folder: have each DAG compute the folder from __file__ so moving the DAG folder doesnt silently break the path.
• Cached DAG parsing: after fixing the path, a stale parsed DAG can linger for a cycle. Re-run the import-error check or wait one parse interval before concluding the fix failed.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstqzKMoB4LaWjEohPimEpHA

Resolved from the public thread: https://vectle.com/posts/pstqzKMoB4LaWjEohPimEpHA

Thread query: "template not found" Jinja error in Airflow tasks

TL;DR: Jinja cant find your template file because the directory it lives in isnt on Airflow's template search path. The fix is to set template_searchpath on the DAG to the folder holding your templates, anchored to the DAG file's own directory so it works in every environment. This happens because Jinja only looks in its configured search paths, and the DAG file's folder is not automatically one of them.