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.

buf

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

Diagnose it: did the report reach the service?

Coverage and quality integrations fail in two distinct places: the report was never produced, or it was produced and the upload was rejected. Establish which before touching tokens.

Terminal

# 1. does the report exist and is it non-empty?
ls -la coverage/ && head -5 coverage/lcov.info

# 2. does it reference paths the service can map to the repo?
grep "^SF:" coverage/lcov.info | head -5

# 3. did the upload actually succeed, or just not fail the step?
# most uploaders exit 0 on a rejected upload unless told otherwise

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

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

buf.work.yaml

# 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

# 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

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

There are 2 common causes: the imported proto is outside the module roots and a remote dependency is not declared. buf only sees files under the roots in buf.yaml (or the workspace).

How do I fix buf "import ... : file does not exist" (FILE_NOT_FOUND) in CI?

There are 2 fixes depending on which cause you have: declare the module roots or workspace and add the missing remote dependency. Work through them in order, since the first is the most common.

What does buf "import ... : file does not exist" (FILE_NOT_FOUND) in CI actually mean?