Earthly "Earthfile syntax error" in CI

By Kaveh Alemi·Latchkey

Earthly parses the entire Earthfile before it builds anything. A syntax error, an unknown command, or a missing VERSION header stops parsing and aborts the run with the offending line.

What this error means

earthly fails with "Error: ... syntax error" and a line number, or "the first command has to be the VERSION command", before any target executes.

Error: failed to parse Earthfile: Earthfile line 4:1 syntax error: unexpected token "COPY"
Error: the first command has to be the VERSION command

Common causes

Missing or misplaced VERSION header

Modern Earthfiles must open with a VERSION command. Without it, the parser rejects the file.

An unknown command or bad indentation

A misspelled command, a tab/space mix, or a command outside a target breaks the grammar the parser expects.

How to fix it

Start with a VERSION line

Declare the Earthfile version as the first command so the parser knows the syntax to expect.

VERSION 0.8
FROM golang:1.22
WORKDIR /app

Validate the Earthfile

1. Read the reported line and column in the error.
2. Fix the command name or indentation on that line.
3. Re-run a lightweight target to confirm parsing succeeds.

earthly +base

How to prevent it

• Keep VERSION as the first line of every Earthfile.
• Use a consistent indentation style, not mixed tabs and spaces.
• Lint Earthfiles in a pre-commit hook.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation