Crystal "Error: can't find file" in CI

Crystal resolves each require to a file under the project, the standard library, or lib/. "can't find file" means none of those locations holds the required path, often because shards were never installed.

What this error means

Compilation stops with "Error: can't find file X" or "can't find file './foo' relative to ...", naming the require it could not resolve.

crystal

In src/app.cr:1:1

 1 | require "kemal"
     ^
Error: can't find file 'kemal'

Common causes

Dependencies were not installed

A require "shardname" resolves under lib/, which only exists after shards install populates it. A clean runner has no lib/ yet.

A wrong relative path in the require

A require "./foo" points at a file that does not exist at that relative path, so resolution fails.

How to fix it

Install shards before building

Run shards install so lib/ is populated from shard.yml.
Build or run the project afterwards.
Confirm the required shard name matches the dependency key in shard.yml.

Terminal

shards install
crystal build src/app.cr

Correct a relative require path

Point the require at the real file location relative to the requiring file.

app.cr

require "./models/user"

How to prevent it

Run shards install as an early CI step.
Match require names to shard.yml dependency keys.
Keep relative require paths in sync with the file layout.