Configure the Node.js main file

On app hosting, the platform does not guess how to start your project: it runs the file named in the MAIN_FILE setting, which defaults to index.js. A wrong path produces a process that starts and exits immediately, usually with Cannot find module in the console. This page shows how to set the entry point and fix path errors.

What the main file means

MAIN_FILE holds the path Node.js should execute, relative to the project root. If your entry point sits at the root, the value is just index.js. If it lives in a subfolder, use src/server.js: the path starts at the service root, not at the folder where you uploaded the archive.

The file must be JavaScript the selected runtime can execute:

• CommonJS: require(...) and module.exports, with a .js or .cjs extension.
• ES modules: import ... from ..., with a .mjs extension, or .js plus "type": "module" in package.json.

A .ts file does not run directly: compile it first, then point to the output, for example dist/index.js.

MAIN_FILE or start script

Two mechanisms can coexist: the main file run by the platform (node index.js) and the start script in package.json. Keep one source of truth. If npm start runs node dist/server.js, point MAIN_FILE at the same file, or you will debug two different paths depending on how the service starts.

A common case: the project builds into dist/ but MAIN_FILE still targets index.js. The source file may contain untranspiled import statements or no longer exist after the build. Check the actual folder contents after compilation, not just your local repository.

Fixing a missing file

The typical error is Error: Cannot find module '/home/container/index.js' or MODULE_NOT_FOUND. In the panel console, list the files:

ls -la
find . -maxdepth 3 -name "*.js" -not -path "./node_modules/*"

Three causes are common:

1. Nested archive: the zip created my-project/my-project/index.js. Move the contents to the root or fix the path.
2. Case: Linux treats Index.js and index.js as different files. Rename with the exact case.
3. Wrong folder: the file is in src/ but MAIN_FILE points at the root.

After fixing it, restart the service and read the log from the first line, not just the last.

Check

• The log shows your startup message or listening on ....
• The service stays up for more than a few seconds, with no restart loop.
• The health route, if you have one, returns 200.
• After a rename, MAIN_FILE and internal imports are updated.

Keep a stable entry point at the root (index.js) that imports the rest from src/. It rarely changes, so MAIN_FILE stays correct as the internal layout evolves.