Diagnosing PyScript Initialization and Runtime Errors in Browser Applications

Recognizable condition

When you load a page that contains <py-script> tags, the Python code does not run. The browser console shows one of the following symptoms:

• "Failed to instantiate module pyscript"
• "Uncaught (in promise) TypeError: pyscript is not defined"
• Blank page output despite correct <py-script> markup

These symptoms indicate that the PyScript loader could not initialize its WebAssembly runtime or could not execute the user‑provided script.

Cause and diagnostic table

Possible cause	What to look for
Missing or outdated pyscript.js link	Network request for pyscript.js returns 404 or an old version (e.g., pre‑2024)
Incorrect script tag order	<py-script> appears before the <script defer src="...pyscript.js"> tag
Wrong MIME type for .wasm file	Response Header Content-Type is not application/wasm (often text/plain or application/octet-stream)
CORS blocking the .wasm fetch	Network error: "Access to fetch at … from origin … has been blocked by CORS policy"
Content Security Policy blocking WebAssembly compilation	Console error: "Refused to compile or instantiate WebAssembly because … violates the following Content Security Policy directive: …"
Invalid py-config JSON or unavailable packages	Console error about malformed JSON or missing package in py-config

Ordered checks

1. Verify network requests for pyscript.js and the .wasm file
   1. Open DevTools → Network tab.
   2. Reload the page.
   3. Filter by "pyscript.js" and confirm the request status is 200 and the Response Headers show Content-Type: application/javascript.
   4. Find the request for the WebAssembly binary (usually named pyscript.wasm or similar) and verify status 200 with Content-Type: application/wasm.
   Where to run: Browser DevTools (Chrome, Firefox, Edge). No special permissions needed. Risk: None; this is read‑only inspection.
2. Confirm script tag order
   1. In the Elements tab, locate the <head> or top of <body>.
   2. Ensure the <link rel="stylesheet" href="...pyscript.css"> (if used) and <script defer src="...pyscript.js"> appear before any <py-script> tags.
   Risk: Reordering tags is safe; just reload to see effect.
3. Inspect CSP headers
   1. In the Network tab, select the main document request.
   2. Under Response Headers, look for Content-Security-Policy or Content-Security-Policy-Report-Only.
   3. Check whether the policy includes script-src, worker-src, or lacks wasm-unsafe-eval.
   Where to run: Same DevTools Network pane. Risk: Reading headers is safe.
4. Check for CORS errors on the .wasm request
   1. In the Network tab, click the .wasm request.
   2. Look at the Status column; a CORS block shows as (canceled) or (failed) with a tooltip describing the CORS policy violation.
   3. If present, note the Origin and the Access-Control-Allow-Origin header (if any) returned by the server.
   Risk: None; observation only.
5. Validate py-config (if used)
   1. Search the HTML for <py-config>.
   2. Copy its content and paste into a JSON validator (e.g., jsonlint.com) to ensure it is valid JSON.
   3. Confirm that any listed packages under "packages" are known to work with the PyScript version you are loading.
   Risk: None; read‑only.

Fixes tied to findings

Missing or outdated pyscript.js

Add or correct the script tag with a specific, matching version. Example for version 2024.1.0:

<link rel="stylesheet" href="https://pyscript.net/releases/2024.1.0/pyscript.css"/>
<script defer src="https://pyscript.net/releases/2024.1.0/pyscript.js"></script>

Place this before any <py-script> block. After updating, reload the page and verify the Network tab shows a 200 response for the new URL.

Incorrect script tag order

Move the <script defer src="...pyscript.js"> tag (and its stylesheet, if used) to appear earlier in the document. A minimal correct ordering:

<head>
  <link rel="stylesheet" href="https://pyscript.net/releases/2024.1.0/pyscript.css"/>
  <script defer src="https://pyscript.net/releases/2024.1.0/pyscript.js"></script>
</head>
<body>
  <py-script>
    print('Hello from PyScript')
  </py-script>
</body>

Wrong .wasm MIME type

Configure your web server to serve .wasm files with application/wasm. For Nginx, add:

# In the server or location block
application/wasm wasm;

For Apache, use:

AddType application/wasm .wasm

After changing the config, reload the server and confirm in DevTools that the .wasm request now reports Content-Type: application/wasm.

CORS blocking .wasm fetch

Either host the .wasm file on the same origin as the HTML page, or enable CORS on the server serving the file. Example for Nginx to allow a specific origin:

location ~ \.wasm$ {
    add_header Access-Control-Allow-Origin "https://example.com" always;
    add_header Access-Control-Allow-Methods "GET, OPTIONS" always;
    add_header Access-Control-Allow-Headers "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range" always;
    if ($request_method = 'OPTIONS') {
        add_header Content-Length 0;
        add_header Content-Type text/plain;
        return 204;
    }
}

Replace https://example.com with the origin of your page. After applying, reload and verify that the .wasm request no longer shows a CORS error.

CSP blocking WebAssembly

Update the Content Security Policy to allow WebAssembly compilation and the needed script/worker sources. A minimal permissive policy for testing:

Content-Security-Policy: script-src 'self'; worker-src blob:; wasm-unsafe-eval 'self';

In production, tighten the policy using nonces or hashes instead of wildcards. After deploying the updated header, reload the page and ensure no CSP‑related errors appear in the console.

Invalid py-config or missing packages

Ensure the py-config block contains valid JSON and lists only packages available for the PyScript version. Example:

<py-config>
{
  "packages": ["numpy", "matplotlib"]
}
</py-config>

If a package is not available, remove it or replace it with a compatible version. After fixing, reload and check that the console no longer reports package‑resolution errors.

Escalation criteria

If the checks and fixes above do not resolve the issue:

1. Capture the full console stack trace (right‑click → Save as…) and note the exact error messages.
2. Try loading the latest nightly PyScript build from https://pyscript.net/latest/pyscript.js to rule out a known bug in the released version.
3. Test the page in a clean browser profile or incognito window to exclude extensions or cached settings that might affect CSP or CORS.
4. If the problem persists, file a detailed issue on the PyScript GitHub repository. Include:
• The minimal HTML snippet that reproduces the problem.
• Relevant server configuration snippets (MIME type, CORS, CSP headers).
• Browser version and operating system.
• The console trace and network log (as a HAR file if possible).

Limitations and practical verification

These steps assume you can modify the HTML and server configuration. If you are on a hosted platform that does not allow custom headers or MIME type changes, you may need to use a proxy or contact the platform support.

To verify that the diagnostic succeeded, add a simple test block after applying fixes:

<py-script>
print('PyScript OK')
</py-script>

Reload the page. If the text “PyScript OK” appears on the page (inside the <py-script> output area or a designated <div>) and the console shows no errors, the initialization is working.