protoc "X.proto: File not found" import path in CI

protoc resolves every import statement against its import paths, not the filesystem directly. "File not found" means the imported file is not under any directory passed with -I (--proto_path).

What this error means

protoc fails with "google/protobuf/timestamp.proto: File not found." or "common/types.proto: File not found." followed by "Import ... was not found or had errors."

common/types.proto: File not found.
api/v1/user.proto:5:1: Import "common/types.proto" was not found or had errors.

Common causes

The import root is missing from -I

The imported path is relative to a proto root you never passed with -I, so protoc searches the wrong directories and finds nothing.

CI runs protoc from the wrong working directory

Import paths are resolved relative to --proto_path; a job run from a different directory than local breaks the relative lookup.

How to fix it

Add the proto root with -I

1. Identify the directory that makes the import path valid.
2. Pass it with -I (repeat -I for multiple roots).
3. Keep import statements relative to those roots.

protoc -I proto -I third_party/protos \
  --go_out=gen proto/api/v1/user.proto

Include well-known type roots when needed

Imports like google/protobuf/timestamp.proto need the include directory that ships with protoc on the path.

protoc -I proto -I /usr/include \
  --go_out=gen proto/api/v1/user.proto

How to prevent it

• Keep all proto roots explicit with -I and consistent between local and CI.
• Run protoc from the repository root so relative paths match.
• Adopt buf, which resolves imports from buf.yaml roots automatically.

Related guides