Diagnosing p5.js preload() Asset Loading Failures

Recognizable Condition

When a p5.js sketch runs, the draw() function throws errors such as "Cannot read property 'width' of null" or "Failed to load image: 404 Not Found". The assets referenced in preload() remain undefined after the preload phase finishes, causing the sketch to break or display blank.

Cause / Diagnostic Table

Possible Cause	What to Look For
Incorrect asset URL (typo, wrong path)	Console shows 404 errors for the specific file.
CORS restriction when loading from another domain	Console shows "Access to image at … from origin … has been blocked by CORS policy".
preload() defined incorrectly (outside sketch, missing async, or overwritten)	No console output from preload(); the function never runs.
Network throttling or offline environment	Requests stay pending; no error appears but assets never load.
Local file:// URL blocked by browser security	Asset fails silently or with a "Not allowed to load local resource" message.

Ordered Checks

1. Verify the sketch structure – Ensure preload() is a top‑level function inside the same file that defines setup() and draw(). It must not be wrapped inside another function or class unless you are using instance mode correctly.
2. Check console for network errors – Open DevTools → Console and reload the page. Look for lines beginning with "Failed to load image:" or "Failed to load sound:". Note the exact URL shown.
3. Test the asset URL directly – Copy the URL from the console error and paste it into a new browser tab. If the tab shows a 404, the path is wrong; if it shows a CORS warning, the server lacks appropriate headers.
4. Confirm preload() execution – Insert a temporary print('preload running') statement at the start of preload(). Reload and verify the message appears in the console. If it does not, the function is not being called.
5. Check for local file usage – If the URL begins with file://, note that most browsers block image/audio loading from this scheme for security reasons.
6. Simulate a slower network – In DevTools → Network tab, set throttling to "Slow 3G" or "Offline" and reload. Observe whether requests stay pending indefinitely.

Fixes Tied to Findings

• Wrong URL or typo – Correct the path relative to the sketch’s HTML file. For example, change loadImage('assets/img.png') to loadImage('./assets/img.png') if the file is in a sibling folder.
• CORS block – Serve the asset from the same origin as the sketch, or configure the remote server to send Access-Control-Allow-Origin: * (or your specific origin). If you cannot change the server, use a proxy that adds the header.
• Misplaced preload() – Move the function to the global sketch scope:

  function preload() {
    img = loadImage('images/photo.jpg');
  }
  function setup() { createCanvas(400,400); }
  function draw() { background(200); image(img,0,0); }
  

  If you are using instance mode, ensure you pass the preload function to the p5 constructor:

  new p5(function(p) {
    p.preload = function() { this.img = p.loadImage('photo.jpg'); };
    p.setup = function() { p.createCanvas(200,200); };
    p.draw = function() { p.background(100); p.image(this.img,0,0); };
  });
  

• Network throttling/offline – Ensure you are connected to the internet or disable throttling in DevTools. For testing offline behavior, bundle assets with the page and use relative URLs.
• Local file:// usage – Serve the sketch via a local web server (e.g., python -m http.server 8000 or npx serve) and load the page at http://localhost:8000/sketch.html. This bypasses the browser’s file‑origin restrictions.

Escalation Criteria

If after performing the checks above the assets still fail to load:

1. Confirm that the server returns the correct MIME type (e.g., image/png for PNG files). Use DevTools → Network → click the request → Headers → Content-Type.
2. Test with a known‑good placeholder URL (e.g., https://via.placeholder.com/150) to isolate whether the problem is the asset or the loading code.
3. Review any Content Security Policy (CSP) headers that might block image or media sources; adjust the policy to allow the needed origins.
4. If the issue persists across multiple browsers, consider filing a bug in the p5.js repository with a minimal reproducible example that includes the HTML, sketch code, and the exact asset URL.