Separate missing templates from static-file delivery failures

Understand the likely causes

• Likely causes include a misspelled namespaced template, a missing installed app or loader path, the wrong settings profile, an absent collected artifact, a mismatched manifest, or an incorrect public URL prefix.
• A locally found source file does not prove the web server can serve the deployed artifact. Uploaded media also follows a different trust and storage policy and should not be folded into a static-file repair casually.

1. Identify which resource lookup failed

Record the exception or exact failed asset URL and the active settings profile without dumping secrets. A server template error occurs before a complete page can be rendered; an asset 404 can occur after valid HTML reaches the browser. Inspect the rendered link or script URL rather than the template source alone. Confirm filename case, app namespace, and deployment base path. Preserve the failing request and artifact identity so another person can reproduce the same boundary. Do not change template loaders to fix a URL that the web server routes elsewhere.

2. Inspect the configured template search

Check the selected template backend, configured directories, app directories, and exact template name. App namespaces such as catalog/list.html avoid collisions with unrelated list.html files. In restricted development evidence, inspect attempted loaders and locations; do not publish private filesystem paths unnecessarily. The local example uses an in-memory loader and proves that the declared name resolves while another name raises the expected exception. It does not import a project or search its files. Once the cause is known, repair the name, app registration, directory, or loader configuration that actually owns the lookup.

from django.conf import settings
settings.configure(
    SECRET_KEY="synthetic-course-key",
    USE_I18N=False, USE_TZ=True,
    INSTALLED_APPS=[],
    DATABASES={"default": {"ENGINE": "django.db.backends.sqlite3", "NAME": ":memory:"}},
    DEFAULT_AUTO_FIELD="django.db.models.AutoField",
    ALLOWED_HOSTS=["testserver"],
)
import django
django.setup()

from django.template import Context, Engine, TemplateDoesNotExist
engine = Engine(loaders=[("django.template.loaders.locmem.Loader", {"catalog/list.html": "<h1>{{ title }}</h1>"})])
print(engine.get_template("catalog/list.html").render(Context({"title": "Course list"})))
try:
    engine.get_template("catalog/missing.html")
except TemplateDoesNotExist:
    print("Missing template diagnosed")

<h1>Course list</h1>
Missing template diagnosed

3. Trace static discovery, artifact, and serving separately

For an asset failure, verify the source finder can locate the namespaced path, then inspect the reviewed build artifact and manifest, then the actual serving route. STATICFILES_DIRS, STATIC_ROOT, and STATIC_URL have different roles and must not be swapped as guesses. A manifest backend needs consistent processed files and references; hard-coded hashed filenames can drift. Use the normal static template tag under the configured backend. Do not run deployment or collection commands against an unidentified environment merely to make the symptom disappear. Choose the approved release process only after its source and destination are established.

4. Verify the repaired path and compatible release

Reload the actual page and inspect the resource response, media type, and content under the intended public base path. Test both a fresh request and the documented cache behavior. Keep required previous hashed assets available during a compatibility window when old pages can still reference them. A successful filesystem lookup is not a substitute for this serving evidence. Check that private uploads have not become public executable assets as a side effect of the repair. Remove temporary debug overrides and confirm the behavior survives the saved settings and reviewed artifact.

Keep it from recurring

• Namespace templates and static paths, keep build manifests with their artifacts, and test representative rendered pages under the deployment base path. Treat static publication and uploaded-media policy as separate responsibilities.