Crystal shards "Failed to resolve dependencies" in CI

shards resolves the version constraints in shard.yml against each dependency's available tags. "Failed to resolve dependencies" means no combination satisfies all constraints at once.

What this error means

shards install or shards update fails with "Error: Failed to resolve dependencies" and a message naming the conflicting requirement or unsatisfiable version.

crystal

Resolving dependencies
Error: Failed to resolve dependencies:
  Unable to satisfy the following requirements:
  - `kemal (~> 1.4.0)` required by `shard.yml`

Common causes

A constraint matches no published tag

A version requirement in shard.yml points at a range with no matching git tag, so the resolver has nothing to pick.

Two dependencies demand incompatible versions

Two shards require non-overlapping versions of a shared dependency, so no single version satisfies both.

How to fix it

Loosen or correct the constraint

Read which requirement shards reports as unsatisfiable.
Adjust the version constraint in shard.yml to a published range.
Run shards update and commit the new shard.lock.

shard.yml

dependencies:
  kemal:
    github: kemalcr/kemal
    version: "~> 1.6"

Update shards that cap a shared dependency

Bump the lagging shard so the shared dependency can move to a satisfiable version.

Terminal

shards update

How to prevent it

Keep version constraints aligned with published tags.
Commit shard.lock so CI installs the resolved set.
Update related shards together to avoid shared-dependency conflicts.