GCP functions-framework "Could not load the function" in CI

By Kaveh Alemi·Latchkey

The Functions Framework starts a local server that imports your source module. If that import throws (a syntax error, a missing dependency, or a bad path), the framework reports it could not load the function and exits.

What this error means

Running functions-framework locally in CI fails with "Provided module can't be loaded" or "Could not load the function, shutting down." followed by the underlying import error.

Provided module can't be loaded.
Did you list all required modules in the package.json dependencies?
Detailed stack trace: Error: Cannot find module './lib/db'
Could not load the function, shutting down.

Common causes

A dependency or local file is missing

The source module imports a package not in dependencies, or a relative file that is not in the build, so the import fails.

Wrong source path

The --source argument points at a file or directory that does not export the target, so the framework cannot load it.

How to fix it

Fix the failing import

1. Read the "Detailed stack trace" line to see which module failed.
2. Install the missing dependency or fix the relative path.
3. Re-run functions-framework.

npm ci
npx functions-framework --target=helloWorld --source=index.js

Point --source at the right module

Ensure the source file exports the target function name the framework loads.

exports.helloWorld = (req, res) => res.send('ok');

How to prevent it

• List every runtime import in package.json dependencies.
• Point --source at the module that exports the target.
• Run functions-framework in CI to catch load errors before deploy.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation