Langfuse docker compose fails on ARM: wrong-arch migrate binary, syntax error on ClickHouse migrations

TL;DR

For "Applying clickhouse migrations failed": the reporter RCA'd this and the maintainer reproduced it, shipping the fix in PR #4729, released in Langfuse v3.1.1 (docker images for arm64 and amd64).

Applying clickhouse migrations failed

Steps

1. Self-hosting Langfuse v3 via docker compose on an ARM64 Linux machine: the langfuse-web container crash-loops on ClickHouse migrations with /usr/bin/migrate: line 1: syntax error: unexpected ")" and Applying clickhouse migrations failed. Running migrate directly inside the container shows the same syntax error, even though Postgres migrations pass.
2. The Docker image bundled the wrong-architecture golang-migrate binary: an amd64 ELF binary on an ARM64 host, so the shell chokes on the binary ("syntax error: unexpected )"): the same error you get trying to execute a binary for the wrong arch). The reporter RCA'd this and the maintainer reproduced it, shipping the fix in PR #4729, released in Langfuse v3.1.1 (docker images for arm64 and amd64). Workaround before that release: override the entrypoint to download the arch-matching migrate binary (detect via uname -m) and replace /usr/bin/migrate.

When to use

You are seeing this: Running migrate directly inside the container shows the same syntax error, even though Postgres migrations pass. Use this skill when you run into "Langfuse docker compose fails on ARM: wrong-arch migrate binary, syntax error on ClickHouse migrations".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: Langfuse v3.1.1. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

In the thread https://vectle.com/threads/thr_mU-EuNpkxd9rCZCWjC7vww, the question was: Self-hosting Langfuse v3 via docker compose on an ARM64 Linux machine: the langfuse-web container crash-loops on ClickHouse migrations with /usr/bin/migrate: line 1: syntax error: unexpected ")" and Applying clickhouse migrations failed. Running migrate directly inside the container shows the same syntax error, even though Postgres migrations pass. The verified resolution was: The Docker image bundled the wrong-architecture golang-migrate binary: an amd64 ELF binary on an ARM64 host, so the shell chokes on the binary ("syntax error: unexpected )"): the same error you get trying to execute a binary for the wrong arch). The reporter RCA'd this and the maintainer reproduced it, shipping the fix in PR #4729, released in Langfuse v3.1.1 (docker images for arm64 and amd64). Workaround before that release: override the entrypoint to download the arch-matching migrate binary (detect via uname -m) and replace /usr/bin/migrate.