Introduction

Loading a TensorFlow.js model from a "local file system" means different things in the browser and in Node.js. In Node.js, TensorFlow.js can read a real filesystem path through the file:// scheme, while in the browser you usually either serve the model over HTTP or let the user pick the model files through a file input.

Load from the local filesystem in Node.js

If your code runs under Node.js, use @tensorflow/tfjs-node and point tf.loadLayersModel or tf.loadGraphModel at the model JSON file with a file:// URL.

1import * as tf from "@tensorflow/tfjs-node";
2
3async function main() {
4  const model = await tf.loadLayersModel(
5    "file:///Users/markqian/models/my-model/model.json"
6  );
7
8  const input = tf.zeros([1, 10]);
9  const output = model.predict(input);
10  output.print();
11}
12
13main().catch(console.error);

This works because the Node.js binding has filesystem access. The .json file must be next to the referenced weight shard files, usually named something like group1-shard1of1.bin. TensorFlow.js reads the JSON first, then follows the weight paths listed inside it.

If you are loading a converted SavedModel or GraphModel, the API changes but the storage rule is the same:

1import * as tf from "@tensorflow/tfjs-node";
2
3const model = await tf.loadGraphModel(
4  "file:///Users/markqian/models/object-detector/model.json"
5);

In the browser, you cannot read arbitrary paths directly

A browser app cannot normally open file:///Users/.../model.json the way Node.js can. Browsers restrict direct filesystem access for security reasons.

If the user has the model files on disk and needs to load them locally in a web page, the usual solution is a file picker plus tf.io.browserFiles:

1<input id="files" type="file" multiple />
2<script type="module">
3  import * as tf from "https://cdn.jsdelivr.net/npm/@tensorflow/tfjs@latest/dist/tf.min.js";
4
5  const input = document.getElementById("files");
6
7  input.addEventListener("change", async () => {
8    const files = Array.from(input.files);
9    const modelJson = files.find((file) => file.name.endsWith("model.json"));
10    const weightFiles = files.filter((file) => file.name.endsWith(".bin"));
11
12    const model = await tf.loadLayersModel(
13      tf.io.browserFiles([modelJson, ...weightFiles])
14    );
15
16    console.log("Model loaded:", model);
17  });
18</script>

That pattern is local from the user's perspective, but it is not the same thing as a direct filesystem path. The user explicitly grants the page access to the chosen files.

Serving the model from a local development server

For browser development, the most common setup is to run a local HTTP server and load the model by URL:

1import * as tf from "@tensorflow/tfjs";
2
3async function loadModel() {
4  const model = await tf.loadLayersModel("http://localhost:8080/model/model.json");
5  return model;
6}

This is often easier than wiring up file inputs, especially when the application itself already has a dev server. It also matches how the app will usually load the model in production.

The key detail is that TensorFlow.js will request the model.json file first and then fetch the referenced weight shard files. If the model JSON points at group1-shard1of1.bin, that file must also be available at the expected relative path.

Choose the right loading method

Use file:// only for Node.js scripts, offline tooling, or server-side inference code.

Use tf.io.browserFiles when a browser user should upload local model files manually.

Use http:// or https:// when the browser app can access a server, including a local dev server running on your machine.

Once you separate those cases, the problem becomes much less confusing.

Common Pitfalls

The most common mistake is trying to use file:// inside browser JavaScript and expecting it to behave like Node.js. It usually fails because the browser sandbox does not grant arbitrary disk access.

Another frequent issue is loading only model.json and forgetting the .bin weight files. TensorFlow.js needs both.

Path mismatches are also common. The weight file paths stored in model.json are relative, so moving only one file without the others breaks loading.

Finally, be careful about which API you call. tf.loadLayersModel is for Layers models, while converted Graph models should be loaded with tf.loadGraphModel.

Summary

• In Node.js, load local models with file://.../model.json.
• In the browser, use tf.io.browserFiles for user-selected local files.
• A local HTTP server is often the easiest browser-friendly development setup.
• Keep model.json and the weight shard files together in the expected paths.
• Match the loader to the model type: loadLayersModel for Layers models and loadGraphModel for Graph models.