buf "import ... : file does not exist" (FILE_NOT_FOUND) in CI

By Kaveh Alemi·Latchkey

buf resolves imports from the files in the module roots plus the dependencies declared in buf.yaml. When an import points outside any root and is not provided by a declared dep, buf reports FILE_NOT_FOUND and fails the build or generate.

What this error means

buf build, lint, or generate fails with "<file>.proto:<line>:<col>:import \"<path>.proto\": file does not exist" tagged FILE_NOT_FOUND.

api/v1/service.proto:6:8:import "common/v1/types.proto": file does not exist

Common causes

The imported proto is outside the module roots

buf only sees files under the roots in buf.yaml (or the workspace). An import that lives elsewhere in the repo is not visible.

A remote dependency is not declared

The import is provided by a BSR module, but buf.yaml has no matching deps entry, so buf cannot find it.

How to fix it

Declare the module roots or workspace

1. List the directories that contain your protos in buf.yaml or buf.work.yaml.
2. Make sure every imported file lives under one of those roots.
3. Re-run buf build to confirm imports resolve.

# buf.work.yaml
version: v1
directories:
  - proto
  - common/proto

Add the missing remote dependency

For imports served by the Buf Schema Registry, declare the dep and update the lock.

# buf.yaml
version: v1
deps:
  - buf.build/acme/common
# then: buf dep update

How to prevent it

• Keep all imported protos under declared module roots.
• Declare BSR deps in buf.yaml and commit buf.lock.
• Run buf build in CI before generate to catch import errors early.

Frequently asked questions

Related guides

References

• GitHub Actions documentation